sanity-copilot-eve-template: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents working in this repository.

Project overview

A Slack-based Sanity copilot built on the eve agent framework. Users @mention it in Slack; it manages their Sanity project through the Sanity MCP connection (GROQ queries, schemas, drafts, releases), pulls source material from and drafts into Notion (user-scoped OAuth via Vercel Connect), and stores files in Vercel Blob. Its workflow lives in agent/instructions.md.

The whole agent is defined under agent/. eve discovers capabilities from the filesystem. See ARCHITECTURE.md for the component map, data flow, and boundaries.

Setup & commands

pnpm install        # install dependencies (Node 24.x)
pnpm dev            # eve dev — local TUI; run /login once to connect a model provider
pnpm typecheck      # tsc (TypeScript, no emit)
pnpm check          # ultracite (Biome) lint + format check
pnpm fix            # ultracite (Biome) auto-fix
pnpm build          # eve build
eve deploy          # deploy to Vercel production (use this, not raw `vercel deploy`)
npx eve info        # print the discovered surface + discovery diagnostics
pnpm validate       # check + typecheck + eve info in one command

There is no unit-test suite. Verify changes with pnpm validate (lint, typecheck, and discovery diagnostics must all report 0 errors / 0 warnings), then exercise the agent in the pnpm dev TUI.

eve conventions

• Read the relevant guide in node_modules/eve/docs/ before writing code. Don't invent framework APIs; confirm them against the docs.
• Identity comes from the filesystem, never a name field. A tool at agent/tools/upload_asset.ts is the tool upload_asset; a connection at agent/connections/sanity.ts registers as sanity.
• Authored slots: agent/agent.ts (model), agent/instructions.md (system prompt), agent/tools/*.ts (defineTool, or defineWorkflowTool for durable/delegating tools), agent/connections/*.ts, agent/channels/*.ts, agent/skills/<name>/SKILL.md, agent/subagents/<id>/agent.ts (defineAgent), agent/sandbox.ts. This repo also has agent/subagents/<id>/skills/ and agent/subagents/reviewer/sandbox.ts: subagent sandboxes don't inherit from the root, and the reviewer needs one to read its skill's reference files.
• Tools run in the app runtime (full process.env), one default export per file. Gate destructive tools with approval from eve/tools/approval. Connections accept the same approval field: both sanity.ts and notion.ts pass a policy that substring-matches the qualified tool name against an APPROVAL_REQUIRED_TOOLS list. Sanity gates patch_documents, publish_documents, unpublish_documents, discard_drafts, version_discard, update_dataset, deploy_schema, and deploy_studio; Notion gates update-pages, move-pages, update-data-source, and update-view (creation is ungated).
• Skills are load-on-demand. A packaged skill (<name>/SKILL.md) requires description frontmatter; that description is the routing hint. Skills here: sanity-best-practices, content-modeling-best-practices, portable-text-conversion, portable-text-serialization, seo-aeo-best-practices, content-experimentation-best-practices, and writing-quality.
• Subagents are declared under agent/subagents/<id>/agent.ts (defineAgent, required description). The directory name is the identity (no namespace; it must not collide with a tool name, even when the subagent sets tool: false). defineAgent no longer takes outputSchema; structured output is requested per turn with ctx.agent(<id>).send(message, { outputSchema }) from a defineWorkflowTool. That's why both subagents here set tool: false and the root reaches them through agent/tools/research.ts and agent/tools/review_draft.ts (shared loop in agent/lib/subagent-task.ts); keep each subagent's description in step with its wrapper tool's. A declared subagent runs in a fresh child session and inherits nothing from the root (no skills, connections, tools, or sandbox), so the caller passes everything it needs in the message. Here: researcher and reviewer. The researcher sets defaultTools: false and re-adds only web_search and web_fetch under its own tools/, so it has no sandbox tools. The reviewer carries its own copy of the writing-quality skill under agent/subagents/reviewer/skills/ plus its own sandbox.ts. The copy intentionally diverges from the root skill where the root's references other root-only skills (seo-aeo-best-practices); when editing either copy, keep them in step except for that.
• After editing, check LSP diagnostics / pnpm typecheck and fix type errors before moving on.