atom-eve AGENTS.md

Agent Development Notes

This repo is an installable agent registry. Treat registry/<agent>/... as the source of truth and treat generated JSON as build output.

Start Here

1. Read "Anatomy of an Agent" below — the three parts every agent is made of, what the build derives, and what it enforces.
2. Read registry/<agent>/README.md (the manifest is its frontmatter) and registry/<agent>/SETUP.md (what the agent needs and how to wire it).
3. Edit the agent under registry/<agent>/agent/ — a real eve agent folder copied verbatim on install.

Skills are the task entry points; this file is the detailed reference they point back to:

• Authoring or contributing a new agent → the author-atom-eve-agent skill.
• Writing or deslopifying a registry/<agent>/README.md → the agent-readme skill.
• Installing an existing agent into a project → the install-atom-eve-agent skill.

Do not edit registry.json, public/r/, or public/index.json. They are generated by pnpm generate and ignored by git.

Repository Conventions

• No legacy / backward-compatibility code. This project is not live yet. When you change a structure or convention, change it everywhere to the new form directly. Do not add dual-path detection, migration shims, or "old way" fallbacks — just update all call sites.
• Code is self-documenting; do not add noise comments. No comments that restate the code or narrate a refactor (e.g. "migrating from X to Y" — it reads as false a year later). Only comment a genuinely non-obvious why. Prefer clear names and structure over prose.

How eve and flue actually work (read the real docs)

Build against the real frameworks — never from memory, from the existing agents, or from stub types. Both ship their docs and TypeScript types inside their npm packages; read them before changing any framework-facing code.

• eve — npm eve (filesystem-first durable agents). An agent lives in a single agent/ folder, and everything is filesystem-discovered — agent/agent.ts is optional and tiny when present (defineAgent({ model }) only, no instructions/tools/channels passed in); omit it to take eve's default model. agent/instructions.md (system prompt), agent/tools/*.ts (defineTool from eve/tools, inputSchema accepts Zod / any Standard Schema / plain JSON Schema, execute(input, ctx); filename = tool name), agent/channels/*.ts (slackChannel is bidirectional — handles inbound mentions and posts replies; creds via Vercel Connect), agent/sandbox/sandbox.ts (defineSandbox), agent/schedules/*.ts — defineSchedule is one-of { cron, markdown } or { cron, run }: use markdown (task mode) for a report agent with no external channel (eve runs the agent on the prompt at the cron tick and the report is the session output); use run only to hand the result to a channel via receive(channel, …). Peer deps: ai, zod. Docs: node_modules/eve/docs/.
• flue — npm @flue/runtime. Source under src/: agents are flat files src/agents/<name>.ts (defineAgent(({ id }) => ({ model, instructions, tools, sandbox, skills })) — a factory, capabilities inline). Tools use defineTool from @flue/runtime with Valibot input/output
  • run, passed as tools: [...]. Instructions: import instructions from './x.md' with { type: 'markdown' } (attribute required; inlined at build; *.md → string decl ships in the package). Skills: with { type: 'skill' }. Sandbox: local() from @flue/runtime/node. Slack is inbound-only — outbound posting is an application tool (chat.postMessage). Scheduling is platform cron — Cloudflare wrangler.jsonc + src/cloudflare.ts invoke(workflow,…), or Node via Croner in app.ts; there is no defineSchedule. Docs: node_modules/@flue/runtime/docs/guide/.
• Schemas do NOT cross targets. eve takes Zod (or any Standard Schema); flue hard-requires Valibot specifically — it checks schema["~standard"].vendor === "valibot" at runtime and rejects Zod, so Standard Schema conformance does not help. A tool's schema must be authored per target (Zod for eve, Valibot for flue); only the framework-neutral run() logic, name, description, and types are shared.