eve-agent

name

eve-agent

description

Scaffold and manage an eve agent (Vercel's filesystem-first agent framework) inside a monorepo, as the engine behind a Next.js app. Use this skill whenever the user wants to create, set up, or initialize an eve agent; add a tool, skill, channel, connection, schedule, subagent, or hook to an eve agent; wire a Next.js (or any) frontend to consume an eve agent; or evolve the `apps/agent` part of a project. Trigger this for ANY mention of "eve", "the agent engine", "agent tools", "agent backend", or building the agentic core of an app — even if the user does not say the word "skill". This is the eve counterpart to dev-flow's Next.js skills (design-md-to-app / module-add); use it for the agent the same way you'd use those for the web app. Not for: building the Next.js app itself or its pages/forms (use design-md-to-app / screenshot-to-page / module-add), scaffolding the monorepo (use monorepo-bootstrap), or React Native (eve is a server-side engine, not an RN concern).

eve-agent

Scaffold and manage an eve agent — Vercel's filesystem-first agent framework, built on the open-source Workflow SDK — as the engine of a product. This skill is part of the dev-flow family and shares the same .workflow/ filesystem contract. Where dev-flow's design-md-to-app builds the Next.js app, this skill builds and grows the apps/agent (eve) that the app uses as its engine.

The one rule that matters most

Never guess the eve API. The source of truth is the bundled docs. Once eve is installed, its full documentation lives at node_modules/eve/docs/, and the live docs are at https://eve.dev/docs. Read the relevant doc there and run npx eve --help (or eve info) BEFORE scaffolding or before adding any capability. (Vercel's own official eve skill — npx skills add vercel/eve --skill eve — consists of exactly this rule and nothing else: read node_modules/eve/docs/README.md first.) eve is young and its surface can change between versions; this skill encodes the workflow and conventions, not a frozen copy of the API. If anything in this skill disagrees with the installed docs, the installed docs win.

references/eve-conventions.md carries the cross-cutting rules that apply to every mode — the per-capability import map, identity-by-path, the durability/idempotency contract, the security model, fail-closed auth, and deploy/monorepo wiring. Read it before scaffolding or adding a capability.

The second rule: eve runs every turn as a durable workflow, and an interrupted step re-runs on resume. So any tool with a non-idempotent side effect (payment, delete, email, external write) MUST be made idempotent or approval-gated (approval: always()/once() from eve/tools/approval). eve's defaults are permissive — do not rely on model behavior to prevent sensitive or irreversible actions.

Where the agent lives (monorepo contract)

This skill assumes a monorepo (Turborepo + pnpm), not a single app at the root:

<project-root>/
├─ .workflow/            # dev-flow planning/design metadata (meta.json is the source of truth)
├─ apps/
│  ├─ web/               # Next.js app — the product (built by design-md-to-app)
│  └─ agent/             # eve agent — the engine (built by THIS skill)
└─ packages/
   └─ types/             # re-exports eve's session/event types so web + agent share one contract

The agent is the engine. The web app consumes it through eve's official Next.js integration — the withEve() wrapper mounts eve's routes same-origin and the useEveAgent() hook drives a session from the browser (see references/eve-web-integration.md). The web app never imports the agent's internals as a library, and never hand-rolls the HTTP/NDJSON plumbing that eve already provides. Keep that boundary clean.

The eve project layout (verify against the docs)

A scaffolded eve app (apps/agent) looks like this — confirm against node_modules/eve/docs/:

apps/agent/
├─ agent/
│  ├─ agent.ts            # model & runtime config (root-only)
│  ├─ instructions.md     # system prompt (required for the root agent)
│  ├─ instrumentation.ts  # OpenTelemetry config (root-only, optional)
│  ├─ tools/              # one file per tool, auto-registered by filename
│  ├─ skills/             # on-demand procedures (.md)
│  ├─ channels/           # entrypoints; the default HTTP channel is channels/eve.ts
│  ├─ connections/        # auth for external services
│  ├─ schedules/          # cron-style triggers
│  ├─ subagents/          # specialist child agents
│  ├─ hooks/              # lifecycle subscribers
│  ├─ sandbox/            # sandbox config
│  └─ lib/                # shared helper code
├─ evals/                 # eval cases — SIBLING of agent/, NOT inside it
└─ .eve/                  # build artifacts (generated by `eve build`)

Read state first, then pick a mode

1. If .workflow/meta.json exists, read it. Check stack.agent. (If there is no .workflow/, this is not a dev-flow project — still proceed, just skip the meta.json updates and tell the user.)
2. Run python scripts/check_eve_state.py <project-root> to detect whether the agent is already scaffolded and what capabilities exist.
3. Choose the mode:
   • stack.agent unset / no apps/agent → Scaffold mode (set the agent up once).
   • agent already present → Capability mode (add a tool / skill / channel / connection / schedule / subagent / hook / eval, idempotently).

Do exactly one logical operation per invocation, then stop. Like module-add, this skill is idempotent: re-running an add that already exists detects it and skips.

Scaffold mode

Goal: a running eve agent at apps/agent, wired into the monorepo, exposing its HTTP API, with a baseline eval, and a shared types package the web app re-exports.

Follow references/eve-scaffold.md for the full procedure. In short:

1. Read node_modules/eve/docs/ (install eve first if needed) and run eve info / npx eve --help to confirm the current init flow and folder layout.
2. Initialize the agent inside apps/agent (npx eve@latest init apps/agent, or eve init . from within it). Keep the default HTTP channel (agent/channels/eve.ts) — that is what the web app consumes. The Next.js app provides the UI via useEveAgent(), so you do not need eve's own starter chat UI.
3. Pin the model in agent/agent.ts (the eve scaffold default is anthropic/claude-sonnet-5 via the Vercel AI Gateway; the model can also be defineDynamic with a fallback) and write a real agent/instructions.md. Document the model choice in a comment.
4. Set the channel auth in agent/channels/eve.ts: localDev() for development, a real authenticator (vercelOidc() / jwtHmac() / httpBasic()) for production. eve fails closed in prod — browser traffic is rejected unless an authenticator accepts it.
5. Add at least one baseline eval in evals/ (sibling of agent/) so eve eval has a gate to enforce in CI.
6. Wire apps/agent into the pnpm workspace and turbo.json pipelines (dev, build, lint, typecheck, plus an eval task that runs eve eval).
7. Create / update packages/types so it re-exports eve's session request + stream-event types — do not hand-roll a parallel contract (see references/eve-web-integration.md).
8. Verify: eve info resolves the app, pnpm --filter agent lint typecheck build and eve eval exit 0, and a real HTTP round-trip returns a non-empty response. Document the exact commands you used.
9. Update .workflow/meta.json: set stack.agent = "eve" and append a history entry ({ "skill": "eve-agent", "action": "scaffold", "ran_at": "<ISO8601>" }).

Capability mode

Goal: add ONE capability to an existing agent, following eve's filesystem conventions. Follow references/eve-capabilities.md. The capability types:

• Tool → a single file in agent/tools/<name>.ts using defineTool from eve/tools. The filename becomes the tool name; eve auto-registers it. No manual registration, no orchestration graph. This is the eve analogue of "add a feature" — exactly what an autonomous loop is good at.
• Skill → an on-demand procedure in agent/skills/<name>.md.
• Channel → a new entrypoint via eve channels add web|slack under agent/channels/.
• Schedule → a cron-style trigger under agent/schedules/<name> (root-only; defineSchedule from eve/schedules).
• Connection → MCP or OpenAPI access under agent/connections/<service> (defineMcpClientConnection / defineOpenAPIConnection from eve/connections).
• Subagent → a local child agent dir agent/subagents/<name>/agent.ts (mirrors agent/; no channels/schedules), or a remote one via defineRemoteAgent from eve. There is no defineSubagent.
• Hook → a lifecycle subscriber under agent/hooks/<name> (defineHook from eve/hooks).
• Eval → a new case in evals/ so the quality gate covers the new capability.

For each: read the matching section of node_modules/eve/docs/ first, add the single file following the existing house style in apps/agent, add/extend an eval that exercises it, run the verification gate, then update meta.json history ({ "skill": "eve-agent", "action": "add-<type>", "inputs": { "name": "<name>" } }).

Definition of Done (every mode)

A run is complete only when these pass with exit code 0:

pnpm --filter agent lint typecheck build
pnpm --filter agent eval      # runs `eve eval`

…plus, for scaffold/web-integration work, a real HTTP round-trip to the agent returns a non-empty response (e.g. eve dev --no-ui, then POST /eve/v1/session and read GET /eve/v1/session/:sessionId/stream). If you cannot verify with a command, the task is under-specified — stop and say so rather than guessing.

How this composes with the loop and with dev-flow

• dev-flow owns the web app, this skill owns the agent. They meet at packages/types (re-exported eve types) and at the withEve() proxy in apps/web.
• In an autonomous Claude Code loop (Linear → Claude Code → PR), a Linear issue like "give the agent a tool to do X" maps cleanly to "create agent/tools/x.ts" — let the loop invoke this skill in Capability mode. Linear stays the orchestrator; do not let dev-flow's meta.json phase machine drive the loop.
• Deployment is Vercel-native: eve link pulls AI Gateway credentials, eve deploy ships the agent to Vercel. The agent's model calls bill through the Vercel AI Gateway, separate from any Claude Code subscription used to build it.

Reference files

• references/eve-conventions.md — cross-cutting rules: import map, identity-by-path, durability/idempotency, security model, fail-closed auth, deploy/monorepo wiring, built-in tools.
• references/eve-scaffold.md — full scaffold procedure + monorepo wiring.
• references/eve-capabilities.md — adding tools / skills / channels / connections / schedules / subagents / hooks.
• references/eve-web-integration.md — the official withEve() + useEveAgent() integration and the shared types package.

Bundled scripts

• scripts/check_eve_state.py <project-root> — reports whether the agent is scaffolded, lists existing tools/skills/channels/connections/schedules/subagents/hooks/evals, reads meta.json#stack.agent, and proposes the next step. Run it first.