AGENTS.md · vercel/eve

Sections

1. About eve
2. Repository layout
3. Git workflow
4. Commands
5. Agent-ready product principles
6. Coding principles
7. Research plans
8. Testing
9. End-to-end tests
10. Documentation
11. Changesets
12. Crediting contributors
13. Security

First lines (shown under the repo's Apache-2.0 license)

# AGENTS.md

Guidance for coding agents (and humans) working in this repository. For setup,
PR workflow, and release process, see [CONTRIBUTING.md](./CONTRIBUTING.md).

## About eve

eve is a filesystem-first framework for durable backend AI agents. You author
an agent as a directory on disk — instructions, skills, tools, connections,
channels, subagents, and schedules are all files — and eve compiles and runs it.
See the [README](./README.md) for the full overview and
[`docs/`](./docs) for user-facing documentation.

Always style the framework name as `eve`, lowercase, in user-facing copy,
docs, prompts, comments, and headings.

## Repository layout

- `packages/eve` — the framework and `eve` CLI (the main package)
- `packages/eve-catalog` — internal, unpublished library
- `packages/eve-code` — `@eve/code`, internal source of the `eve/extensions/code` extension shipped in `eve`
- `apps/fixtures` — shared agent fixtures used by e2e, TUI smoke tests, and local dev
- `apps/frameworks`, `apps/templates`, `apps/docs` — framework integrations, templates, docs site
- `docs` — published documentation content
- `e2e/` — fixture-owned `eve eval` end-to-end tests
- `research` — issue-backed implementation plans for proposed changes

## Git workflow

Commits must be cryptographically signed with a GitHub-verified key and include
the DCO `Signed-off-by` trailer. Use `git commit -s` for every commit, and if a
commit is missing the trailer, amend it with `git commit --amend -s --no-edit`
before pushing.

PR descriptions are reviewer-oriented explanations of the problem or decision
behind the change, the solution, meaningful behavior changes, and validation—not
file lists or commit logs. Keep the Summary short and lead with that
justification before implementation details. Link a prior issue or discussion
when one exists, call out important scope boundaries or preserved behavior, and
report only checks actually run. Never create an issue solely to accompany a PR.
Use the [`gh-pr-description`](./.agents/skills/gh-pr-description/SKILL.md)
skill when drafting or updating one.

Once the first implementation is done, use the
[`pr-shepherd`](./.agents/skills/pr-shepherd/SKILL.md) skill to open the PR
early, run a fresh-context review, address and resolve comments, get CI green,
and merge.

## Commands

```sh
pnpm install            # install workspace dependencies
pnpm build              # build all packages
pnpm dev                # watch-mode build + weather fixture on an available local port

pnpm typecheck          # TypeScript across the workspace
pnpm lint               # oxlint (auto-fixes)
pnpm fmt                # oxfmt
pnpm guard:invariants   # mechanical code-invariant checks (runs in CI)
pnpm docs:check         # docs frontmatter and nav validation

pnpm test               # unit + integration
pnpm test:unit          # unit tests (<3s)
pnpm test:integration   # integration tests (several minutes; leave the full run to CI)
pnpm test:scenario      # scenario tests (2–5 min; Turbo builds prerequisites)
pnpm test:framework-fixtures # apps/frameworks smoke builds (Turbo builds prerequisites)
pnpm test:webchat       # web chat template in headless Chromium (needs playwright-core's chromium-headless-shell)
pnpm test:e2e           # fixture-owned eve eval suites (CI only)
pnpm test:tui           # TUI smoke scripts (not e2e)
```

We value fast local iteration whenever possible. Run `pnpm fmt`, `pnpm lint`,
and `pnpm typecheck` frequently to catch inexpensive failures early, and run
unit tests after material behavioral changes. Integration and scenario tests
are comparatively slow, so do not run them after every change; run the
narrowest relevant test when a change needs behavioral validation. Copy edits,
typo fixes, small code reorganizations, and similar non-behavioral changes can
proceed without local integration or scenario runs. CI is always the official
line of defense, and every required check must pass before merge.

Do not run a whole integration or scenario tier, or a whole multi-channel
suite such as the channel conformance suite, locally unless the task
expressly needs it (for example, the user asks, or you are chasing a failure
only the full run reproduces). Scope local runs to the files and test names
your change touches with a path and `-t` filter, and leave the full suites to
CI.

## Agent-ready product principles

1. **Docs is priority #1.** Agents read your docs before they ever touch your
   product. If the docs are incomplete or ambiguous, the agent is lost before it
   starts.

2. **Authentication is the biggest friction point.** Auth is where agent runs
   stall most often: hidden prerequisites, unset keys, and OAuth flows that
   quietly assume a human is at the keyboard.

3. **Error messages make or break recovery.** A vague or misleading error sends
   an agent spiraling; a precise, actionable one lets it self-correct. Your errors
   are documentation.

4. **CLIs often assume a human is present.** Interactive prompts, TTY checks, and
   "press y to continue" break agents that have no way to answer back.

5. **Discoverability determines whether agents find you at all.** `llms.txt`,
   typed SDKs, MCP servers, machine-readable specs. If an agent can't discover
   your surface, it reaches for a competitor it already knows.

6. **Better for agents, better for humans.** Almost everything that makes a tool
   agent-ready, from clear docs to precise errors to sane defaults, makes it
   better for human developers too.

## Coding principles

1. **Public APIs are sensitive.** They usually require a research doc proposing the
   change, alongside proper e2e tests covering golden paths and known failure modes.
   They also require proper and legible documentation.

2. **The core is lean and powerful**. The framework core should be simple yet highly
   expressible i.e., `eve` can be built with `eve`. This means that changes in
   `execution/` and `harness/` should be only done when strictly necessary. The
   core should expose hooks and internal APIs so that broad functionality is built
   on top of it.

3. **KISS**. Keep things simple. If there are 5 ways to do something, the simplest
   and more obvious one should be the preferred option. Code should be legible and
   obvious.

4. **Code is liability**. Each net-new introduced snippet should earn its right
   to exist. Common abstractions should be reused. Accidental complexity needs
   to be derived to its essence. Entropy must be contained.

5. **Wrap third-party dependencies.** Do not expose third-party APIs as eve
   public APIs. Wrap them in eve-owned surfaces so internals can change freely.
   Add runtime `dependencies` only as a last resort: prefer vendoring code or
   generated artifacts into the repository and listing the source package under
   `devDependencies`. The `eve` package should aim to keep `nitro` as its only
   runtime dependency. This keeps eve installs as small as possible and avoids
   exposure to hijacked nested dependencies that are not pinned directly in the
   main lockfile.

6. **Pre-1.0: prefer breaking changes.** Favor correctness and simplicity over
   backwards compatibility. No legacy fallback logic.

7. **Derive names from file paths.** Connection names, tool names, and similar
   identifiers come from the filesystem path (e.g.
   `agent/connections/linear.ts` → `"linear"`). Do not add redundant `name`
   fields to definitions.

8. **Name definitions for the protocol they target.** Use
   `defineMcpClientConnection`, not `defineConnection`.

9. **All runtime functionality lives in the `eve` package.** Never rely on
   emitted or generated code for runtime behavior.

10. **Comment why, not what.** Default to no comment; well-named code is the
    documentation. Comment only what the code cannot say itself — a non-obvious
    why, an invariant, a surprising edge case. Public API docs (principle 1) are
    the exception.