AIStoreHub Package Vault: Eve
Package Slug: eve
Archetype: agent
Upstream Repository: https://github.com/vercel/eve
Workspace Files & Specifications (69 files)
- .agents/skills/gh-pr-description/SKILL.md (3073 bytes)
--- name: gh-pr-description description: Drafts and reviews GitHub pull request descriptions for the eve repository. Use when opening, updating, or reviewing a PR, or when summarizing a branch for reviewers. metadata: internal: true --- # GitHub PR description Inspect the branch diff, commits, related issue or discussion, tests, docs, and changesets. When updating a PR, read its current body first. ## Write Fill in the Summary and Changes sections of `.github/pull_request_template.md`. Never add a Validation, Test plan, or Checklist section, and delete them from an existing body when you update it. Write for a reviewer, not a changelog. Follow these ASD-STE100 rules where they apply: - Use approved words from the ASD-STE100 dictionary, with one meaning per word. - Use active voice and keep one topic in each sentence. - Limit descriptive sentences to 25 words and procedural sentences to 20 words. - Keep necessary technical terms, proper nouns, and code identifiers. ### Summary - Keep it to one short paragraph: usually 2–4 sentences and about 100 words or fewer. - Lead with the concrete problem, user need, or decision behind the change, then state the approach in a sentence or two. Leave the specifics to Changes. - Link an existing issue or discussion with `Closes #N`, `Related to #N`, or an equivalent when one exists. Do not create an issue solely for a PR. ### Changes A flat list of the changes a reviewer must know, not a narrative. - Put public API changes first: new, changed, or removed exports, options, config fields, CLI commands and flags, events, defaults, and error types. Then list other user-visible behavior changes. - Write one change per bullet, in one sentence where possible. Name the identifier in code format and its entry point when it has one, such as `renderInteractionBlocks()` from `eve/channels/slack`. - Add a short reason with "so" or "because" only when the Summary does not already make it clear. - Prefix breaking changes with `Breaking:` and say what callers must change. - End with preserved behavior, scope boundaries, or follow-ups only when they matter to review. - Usually 2–6 bullets. A one-change PR gets one bullet. Do not nest bullets, add sub-headings, or split the list by commit or original PR. - Do not list files, internal refactors, tests, or checks you ran. Include implementation detail only when it is necessary to assess behavior or risk. Example, from #5733: ```md ### Changes - Scaffolded projects now default to `@vercel/[email protected]` through `DEFAULT_CONNECT_PACKAGE_VERSION`. - The optional `@vercel/connect` peer is now `^2.7.0`, so npm won't pair eve with a connect release that rejects it. - Templates under `apps/templates` are unchanged. They pin stable eve releases, which older connect releases already accept. ``` ## Publish Before publishing, confirm the Summary leads with why the change is needed and Changes lists every public API change. Write the body to a file, then pass it to `gh pr create` or `gh pr edit` with `--body-file`.
- .agents/skills/pr-shepherd/SKILL.md (10747 bytes)
--- name: pr-shepherd description: Takes a finished eve branch from review to merge. Opens the PR early, runs a fresh-context reviewer subagent, fixes critical findings, addresses, replies to, and resolves review comments, pushes, monitors CI (rerunning flaky jobs or fixing real failures), then squash-merges or enables auto-merge. Follow only when the user explicitly asks to shepherd, babysit, land, or merge a PR, or to "get a PR green". Do not start it on your own after finishing an implementation or when only asked to open a PR. metadata: internal: true --- # PR shepherd Start after the first implementation is complete and checked locally. Finish when the PR has no unresolved review threads, no unanswered comments, and green CI on the latest head commit, and it is merged or set to auto-merge. Open the PR first. Review bots and teammates comment while the rest of the work runs, so an early PR gets more feedback in each round. ## 1. Open the PR 1. Make sure the branch is committed with `git commit -s` and that commits are signed (see [`AGENTS.md`](../../../AGENTS.md)). Add a changeset if the change touches the published `eve` package. 2. Run the fast checks from `AGENTS.md`: `pnpm fmt`, `pnpm lint`, `pnpm typecheck`, plus the narrowest relevant unit tests. 3. Push the branch, then open the PR. Use the [`gh-pr-description`](../gh-pr-description/SKILL.md) skill for the body and pass it with `--body-file`. Open it ready for review, not as a draft, unless the user asks for a draft. 4. Record the PR number. Every later step uses it. If a PR already exists for the branch (`gh pr view --json number,url`), reuse it. ## 2. Fresh-context review Spawn one reviewer subagent with no conversation history. Give it the PR number and the branch, not your reasoning. A fresh reviewer catches what the author explains away. Use a prompt like this one: > Review PR #<n> in this repository (`gh pr view <n>`, `gh pr diff <n>`). Read > `AGENTS.md` first and apply its coding, security, testing, docs, and changeset > rules. Read surrounding code as needed to verify behavior. Do not edit files. > Report findings ordered by severity (critical, important, minor). For each > finding, give the file and line, the concrete failure or risk, and a suggested > fix. Say plainly when you find nothing critical. While the reviewer runs, you can already collect PR comments (step 3). Triage the findings yourself. Verify each one against the code before you act. - Fix: correctness bugs, races, security or data-loss risks, broken public behavior or docs, missing tests for changed behavior, a missing changeset, and invariant violations. - Skip: style nits, speculative refactors, and scope creep. Mention notable skipped items to the user in the final report. ## 3. Address PR comments Collect all feedback. Unresolved inline review threads, with the IDs you need to reply and resolve: ```sh gh api graphql -F owner='{owner}' -F repo='{repo}' -F number=<n> -f query=' query($owner: String!, $repo: String!, $number: Int!) { repository(owner: $owner, name: $repo) { pullRequest(number: $number) { reviewThreads(first: 100) { nodes { id isResolved isOutdated path line comments(first: 50) { nodes { author { login } body url } } } } } } }' --jq '.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved | not)' ``` Top-level comments and review summaries (these cannot be resolved): ```sh gh pr view <n> --json comments,reviews \ --jq '.comments[], .reviews[] | select(.body != "") | {author: .author.login, body}' ``` Expect two review bots: - `roboeve[bot]` reviews once, on the commit that opened the PR, usually within 2–15 minutes. It does not review later pushes. - Vercel Agent Review (`vercel[bot]`) runs as a check on every push and can post new threads on later commits. It re-checks its own threads after a fix and resolves them itself, so skip threads it already resolved. Ignore informational bot posts such as Vercel deployment and bundle analysis comments, unless they report a problem this PR caused. For each thread, decide: fix, decline with a reason, or defer to a follow-up. Apply the same triage bar as step 2. Bot suggestions get the same scrutiny as human ones; confirm the problem is real before you change code. If a comment needs a product or design decision only the user can make, ask the user. ## 4. Commit, push, reply, resolve 1. Combine the fixes from steps 2 and 3. Rerun the fast checks and the narrowest tests that cover the fixes. 2. Commit with `git commit -s` and push. Add new commits instead of amending or force-pushing, so reply SHAs stay valid. PRs are squash-merged and `main` does not require branches to be up to date, so do not rebase only to catch up. If `gh pr view <n> --json mergeable` reports `CONFLICTING`, merge `origin/main` into the branch with `git merge --signoff origin/main`. Rebase or force-push only when the user asks or to repair signing or DCO. 3. If the fixes changed behavior that the PR body describes, update the body with `gh-pr-description`. 4. Reply in each thread after the fix is on the remote. Keep replies short and specific, in the style already used on eve PRs: - `Fixed in <sha>. <What changed, in one or two sentences.>` - `Not changing this: <reason grounded in the code or a repo rule>.` - `Agreed, this is a real gap. Tracking it in a follow-up: <scope>.` Reply by thread ID. The REST replies endpoint accepts only a thread's first comment, so it fails on later rounds. ```sh gh api graphql -f id='<thread id>' -f body='Fixed in abc1234. ...' -f query=' mutation($id: ID!, $body: String!) { addPullRequestReviewThreadReply(input: { pullRequestReviewThreadId: $id, body: $body }) { comment { url } } }' ``` 5. Resolve threads that are fixed and pushed. Also resolve bot threads that you declined or deferred, after you reply. Leave declined or deferred human threads open, so the reviewer can accept the reason before merge, and list them in the final report. ```sh gh api graphql -f id='<thread id>' -f query=' mutation($id: ID!) { resolveReviewThread(input: { threadId: $id }) { thread { isResolved } } }' ``` 6. Answer top-level comments that ask for a change or a question with `gh pr comment <n> --body-file <file>`. ## 5. Monitor CI Wait for checks on the new head commit. It can take a minute for them to register after a push. ```sh gh pr checks <n> --watch --interval 60 ``` If your shell cannot block that long, poll `gh pr checks <n>` on an interval. A full round takes about 10–15 minutes, and `test-scenario` and the e2e shards finish last. `gh pr checks <n> --required` shows only the checks that block merge. Advisory checks such as Bundle Analysis and the eve-code benchmark should still pass, but they come second to required checks. For each failure, find the real error before you act. Integration tests log many expected errors, so the first `Error:` lines in a failed log are usually noise. Look for the vitest summary instead: ```sh gh run view <run-id> --log-failed | grep -aE 'Failed Tests|FAIL |Test Files|Unhandled' ``` If every test passed but the job still failed, read the end of the log for a teardown error, hang, or timeout. Classify the failure: - Real: the failure relates to the diff or reproduces locally with the tier config from `AGENTS.md`. Fix it, then go back to step 4. - Already failing on `main`: the same job fails the same way on recent `main` runs (`gh run list --branch main --workflow <file> --limit 10`). A rerun cannot pass, and the fix does not belong in this PR. Do not rerun it; report it to the user as unrelated. - Flaky: the failure does not relate to the diff, and it shows timeouts, network, provider, or deploy errors. Most flakes come from `test-integration` on either OS, `test-scenario`, and `e2e-vercel` fixture deploys. `e2e-local` uses live models, so it can also vary between runs. Rerun only the failed jobs of a flaky failure. GitHub refuses a rerun while any job in that workflow run is still in progress, so wait for the run to finish: ```sh gh run rerun <run-id> --failed ``` Rerun a flaky job at most twice per head commit. If it still fails the same way, treat it as real, or report it to the user with the failing test names. Do not run whole integration, scenario, or e2e tiers locally. Scope local runs to the failing file and test name. ## 6. Loop until done After each push, return to step 3. Teammates may comment at any time, and Vercel Agent Review reviews each new commit. Stop when all of these are true for the latest head commit: - All checks are green, including the Vercel Agent Review check, or the only failures are documented as unrelated and the user knows about them. - There are no unresolved review threads, except ones that wait on a human decision. - No new comments arrived since your last pass. ## 7. Merge When step 6 is done, merge the PR, unless the user asked you not to merge. Check the review state and whether auto-merge is already on: ```sh gh pr view <n> --json reviewDecision,mergeStateStatus,autoMergeRequest,headRefOid ``` PRs to `main` are squash-merged. GitHub uses the PR title as the commit subject and leaves the body blank, so pass the DCO sign-off as the body. Pin the head commit so a push that arrives after your last check cannot merge unseen. - `APPROVED`, with green required checks: squash-merge now. ```sh gh pr merge <n> --squash --match-head-commit <headRefOid> \ --body "Signed-off-by: $(git config user.name) <$(git config user.email)>" ``` - `REVIEW_REQUIRED`: enable auto-merge, so GitHub merges once a code owner approves. Skip this when `autoMergeRequest` is already set. ```sh gh pr merge <n> --squash --auto --match-head-commit <headRefOid> \ --body "Signed-off-by: $(git config user.name) <$(git config user.email)>" ``` - `CHANGES_REQUESTED`: do not merge or enable auto-merge. Report the review to the user. Do not pass `--delete-branch`. GitHub deletes the remote branch after the merge, and the local cleanup can fail in a worktree. Confirm the result with `gh pr view <n> --json state,mergedAt,autoMergeRequest`. ## Final report Give the user the PR URL and a short account of the work: - Reviewer findings you fixed, and notable ones you skipped and why. - Comments you addressed, declined, or deferred, plus threads still open. - CI status on the head SHA, flaky reruns with job names, and real failures you fixed. - Merge state: merged with the squash commit SHA, auto-merge enabled and waiting on approval, or not merged and why. - .agents/skills/technical-writing/SKILL.md (6946 bytes)
--- name: technical-writing description: Write, edit, review, or audit user-facing documentation for the eve repository. Use for changes under docs/, documentation tied to eve APIs or CLI behavior, docs work based on Slack or support feedback, and requests to make eve docs clearer, more natural, or less AI-patterned while verifying claims against current source, tests, CLI help, public releases, and repository conventions. metadata: internal: true --- # Technical writing Write accurate, task-focused documentation for eve. Treat developers and AI agents as readers: make each section easy to scan, retrieve, and act on without relying on unstated context. ## Choose a workflow - For a new page or full rewrite, read [references/writing-workflow.md](references/writing-workflow.md). - For targeted or structural changes to existing pages, read [references/editing-workflow.md](references/editing-workflow.md). - Before finalizing any change, read [references/review-framework.md](references/review-framework.md). - For formatting and terminology, read [references/style-rules.md](references/style-rules.md). - For wording, voice, or AI-pattern concerns, read [references/prose-quality.md](references/prose-quality.md). - For page structure, read [references/content-types.md](references/content-types.md) when the content type is unclear or changing. ## Verify before writing Do not rely on training data for eve behavior. Use this source hierarchy: 1. Current source, public types, and tests in `packages/eve` 2. Current CLI help and setup implementation 3. Existing pages under `docs/` 4. Merged pull requests, changelogs, and release notes 5. Research plans under `research/` as proposed intent, not shipped behavior 6. Support evidence such as Slack threads or issues Use support evidence to identify the reader's problem, not to establish product behavior. Verify commands, flags, API names, defaults, limitations, and examples against the current repository. For a docs-only change, also compare the implementation with the latest public release so the docs do not announce branch-only behavior. When docs accompany product code in the same change, state that dependency during review. If a claim cannot be verified, omit it or report the missing owner or source. Never leave `[VERIFY]` markers in a completed docs change. ## Follow eve conventions - Write `eve` lowercase, including headings and sentence starts when practical. - Use exact public names such as `defineAgent`, `eve dev`, and `eve add channel/slack`. - Distinguish the root agent, the built-in `agent` tool, declared subagents, and remote agents. They have different inheritance and execution semantics. - Distinguish eve connections from Vercel Connect, the model-facing `Workflow` tool from authored Vercel Workflows, and durable session state from sandbox filesystem or attachment storage. - Name diagnostic surfaces precisely: Vercel runtime logs, **Agent Runs**, OpenTelemetry, `eve logs`, and `eve traces` are not interchangeable. - Treat `docs/**` as published documentation. Update `docs/meta.json` when navigation changes. - Keep `.md` files framework-agnostic. Use MDX components only in `.mdx` files and only when nearby pages establish the convention. - Preserve published routes and heading anchors when possible. When moving a page, update authored links and add permanent redirects for old HTML and Markdown URLs. - Prefer TypeScript examples. Include imports and language labels, and verify examples against current exports. - Show only supported commands and flags. Check CLI help or the command implementation before documenting them. - Link to related pages with descriptive text. Include the critical fact locally because retrieved sections may be read without their links. - Leave no page orphaned. Every page needs at least one descriptive inbound body link from a related hub or overview page; a `meta.json` sidebar entry or a routing-table cell alone is not enough. When adding a page, add the inbound link from the page that owns the topic in the same change, and keep every page reachable by following body links from `getting-started`. - Do not document proposed behavior as shipped. Describe unsupported boundaries directly when they affect a user task. - Describe current behavior only. Migration steps, removed options, and renames belong in changesets and release notes, not in `docs/**`. - Document the contract, not the mechanism. Leave out internal modules, algorithms, and data structures unless the reader needs them to configure, debug, or reason about a limit. ## Write for the task - Lead each page and section with the answer or outcome. Feature pages follow the feature page shape in [references/content-types.md](references/content-types.md): opening, minimal example, rules, options, then variants. - Write prose in the reader's words, not eve's runtime vocabulary. See Plain words in [references/style-rules.md](references/style-rules.md). - Address the reader as `you`; use imperative verbs for steps. - Prefer active voice, present tense, concrete nouns, and consistent terms. - Preserve the author's supported meaning, nuance, and uncertainty. Make the minimum effective edit and leave strong prose alone. - Keep one page focused on one primary job. Add a section to an existing page when it already owns the task. - Put the happy path before alternatives and failure modes. - Add troubleshooting where observed failures cluster around a workflow. Use symptoms, verified causes, and concrete next checks. - Write self-contained sections. Repeat the full noun in key statements instead of relying on ambiguous pronouns. - Use specific limits and behavior only when the repository or an authoritative platform source supports them. ## Avoid common failures - Do not invent flags, registry entries, connectors, workarounds, or platform guarantees. - Do not turn one product request into a new page. First decide whether the gap belongs to docs, product, or both. - Do not duplicate broad guides when a focused section or cross-link resolves the problem. - Do not rewrite clear prose merely to match a personal preference. - Do not manufacture examples, opinions, reactions, or specificity to make prose sound more human. - Do not use promotional language, rhetorical questions, filler, or claims that a task is easy, simple, or quick. - Do not use `we` unless describing a deliberate Vercel or eve team action. ## Finish the change 1. Re-read every changed page in full. 2. Verify each new technical claim against its source. 3. Search for contradictory statements and affected cross-links. 4. Confirm added or moved pages have an inbound body link from a related page, so no page is orphaned. 5. Run the review workflow. 6. Check changed prose against the prose-quality reference when wording changed materially. 7. Run `pnpm docs:check` when preparing to push, unless the user requests earlier validation.
- .agents/skills/test-audit/SKILL.md (10041 bytes)
--- name: test-audit description: "Invoke whenever writing, changing, reviewing, or sweeping tests in the eve repository. Authoring gate for new tests plus audit workflow for low-value, slow, implementation-coupled, or duplicative tests and the test-only production seams they demand." metadata: internal: true --- # Test audit Adapted from the OpenClaw [`test-audit`](https://github.com/openclaw/openclaw/blob/main/.agents/skills/test-audit/SKILL.md) skill for eve's test tiers and tooling. Three modes, one value bar. Authoring mode gates every new or changed test at write time. Audit mode runs focused sweeps of tests that re-assert source, duplicate stronger proof, couple behavior to implementation, or keep test-only production seams alive. Continue broad audits as separate coherent follow-up PRs; optimize for confidence, not deletion count. Campaign mode prunes one whole subsystem's test surface (every test file one core area or package owns); before starting one, read [CAMPAIGN.md](CAMPAIGN.md). Read the root [`AGENTS.md`](../../../AGENTS.md) testing section first. It defines eve's four tiers (unit, integration, scenario, e2e); a test belongs in the tightest tier that can express its assertion. ## Authoring gate Before adding any test, answer four questions; a missing answer means do not add it yet: 1. What observable behavior, invariant, or independent contract does it protect? 2. What credible regression makes it fail? 3. Why does existing coverage not already catch that failure? Each contract has one primary test owner at the strongest boundary; another layer needs its own distinct risk, such as a transport or lifecycle failure the owner cannot reach. Prefer extending a table-driven case or shared fixture over a near-duplicate test; consolidate duplicated setup in the same change. 4. Does it need a production seam (export, flag, wrapper, injection hook) that no production caller needs? If yes, move the test to the real boundary instead. Then check the test against every [junk pattern](#junk-patterns); a match fails the gate unless the [retention bar](#retention-bar) names the contract it independently guards. A test that would break under behavior-preserving refactoring is asserting implementation, not behavior; rewrite it at the owning boundary before landing it. Also check its cost. A scenario test that boots a dev server, installs a tarball, or runs a real build must need that subprocess, port, or bundler. If it only needs `import "eve"` to resolve or an in-memory runtime, it belongs in integration (`useTemporaryAppRoots`, `createTestRuntime`). A test that waits out a real production timeout or backoff should use fake timers or an existing public option instead of wall-clock time; do not add a test-only seam to shorten it. Bug regression tests must fail on the pre-fix code for the intended reason and pass after the owner-boundary repair. A regression test that never demonstrably failed proves the mock, not the fix. One regression at the owner boundary covers the bug; do not replay the same scenario at every layer it crosses. ## Junk patterns The shared checklist for both modes: the authoring gate rejects a new test that matches one, and audits hunt for existing tests that do. - assertion-free coverage probes; - self-comparisons and identity copiers; - copied fixtures, inventories, manifests, or export lists; - exact source, import, or string greps; - private predicate or call-shape tests duplicated at real boundaries; - duplicate invocations of the same contract, including the same scenario replayed across several dev-server or build suites; - provider-local replays of shared helpers; - tests whose only purpose is preserving test-only exports, globals, or wrappers; - dead production code whose only callers are tests; - expected values produced by the helper or renderer under test; - mocks that implement the asserted behavior, or one identical mock standing in for different APIs; - fixtures that supply the receipt, admission, or callback ordering the owner should produce, or persistence asserted against a store the path never writes; - capability tests that restate declared flags instead of exercising the delivery or acknowledgement the flag promises; - negative controls that pass for an unrelated reason, such as a denial from a different guard or a rejection the production path never reaches; - names or fixtures that promise more than the input exercises, such as a "terminates the child" test asserting only that the child never completed; - parameter matrices whose rows exercise the same code path; - suites gated on env flags or platforms that no CI job ever sets. ## Value bar Tests justify their maintenance cost by protecting behavior, a credible regression, or an independently meaningful contract. In an audit, an existing test that must change for behavior-preserving source reorganization is suspect, not automatically deletable; the authoring gate still rejects new ones. Before judging a candidate, read the complete test and production owner, its entry point, callers, callees, sibling implementations, overlapping tests, CI routing (`.github/workflows/`), and relevant history. Read root and scoped `AGENTS.md` files first. When the test claims dependency-backed behavior, inspect the dependency source or types directly. ## Discovery Keep discovery read-only and report evidence before editing. Baseline with the JSON reporter so slow files and tests are visible: ```sh pnpm --filter eve exec vitest run --config vitest.<tier>.config.ts \ --reporter=json --outputFile=/tmp/<tier>.json ``` For broad scope, run parallel discovery lanes when available, split along production owner boundaries: - core unit tests (`packages/eve/src/{execution,harness,runtime,compiler,...}`); - CLI, setup, evals, tracing, and instrumentation; - public API, client, channels, and `src/internal`; - integration tier (`*.integration.test.ts`); - scenario tier (`*.scenario.test.ts`, `packages/eve/test/scenarios/`); - other packages and apps (`packages/eve-code`, `packages/eve-catalog`, `apps/docs`, `e2e/`); - a cross-cutting pattern, test-only-export, and console-noise sweep. Outside campaign mode, prefer a few high-confidence candidates over a large speculative inventory. Hunt for the [junk patterns](#junk-patterns). ## Retention bar Keep a test when it independently enforces a public API (`eve/*` exports), protocol, config, migration, storage, security, platform, default, prompt-byte, package, release, or architecture contract. Also keep: - call ordering when order is observable behavior; - regressions with a credible failure mode; - source inspection when it is the cheapest independent guard: it fails when the contract changes (the user-facing key, byte, or path) and survives an identifier-only refactor; - a retained test that fails on the baseline: treat it as a possible product bug, reproduce it, and repair the owner rather than deleting it. Static or slow is not a deletion reason on its own. A slow test with a unique contract gets cheaper (shared boot, fake timers, lower tier), not deleted. A test that resembles implementation may still be the independent contract; prove otherwise before removing it. ## Candidate evidence Record every field below before editing. A missing field means the candidate is not ready for deletion: - exact test name and location; - what failure it can actually detect; - non-test callers of the covered production or support seam; - stronger remaining owner-boundary proof, or why no proof is needed; - relevant history and the reason the test or seam exists; - production or test-support deletion unlocked; - risk, the focused validation command, and time saved when relevant. ## Edit shape Choose one coherent owner-boundary batch. Delete obsolete test-only exports, globals, wrappers, and dead production paths instead of preserving aliases. Move retained regressions to their canonical owners. Consolidate repeated package or dependency assertions into one generic contract. Prefer net-negative production LOC. Do not add replacement tests that restate the same implementation, and do not convert uncertain candidates into cleanup to increase deletion counts. Do not commit fixture trees under `packages/eve/test/fixtures/`; scenario apps stay inline descriptors. ## Validation Never edit source or tests while Vitest is running in the checkout. 1. Run the smallest owner and sibling tests with the tier config, never bare `vitest run`: `pnpm --filter eve exec vitest run --config vitest.<tier>.config.ts <path>`. Run `pnpm --filter eve build:compiled` first if `#compiled/*` changed, and `pnpm build` before scenario runs. 2. For removed source greps or invariant assertions, run the script that owns the real contract, such as `pnpm guard:invariants`. 3. Run `pnpm fmt`, `pnpm lint`, `pnpm typecheck`, then `git diff --check`. 4. When deleted tests were the only callers of production code, `pnpm typecheck` and `pnpm lint` are the proof that nothing else depended on it. 5. Inspect `git diff --numstat`; report production/tooling separately from tests and test support. Report before and after tier timings for speed work. 6. Follow the root `AGENTS.md` changeset rule. Test-only changes need none; removing dead production code from `packages/eve` still needs one. ## Landing and continuation Commit, push, open a PR, or land only when authorized. Sign off every commit (`git commit -s`) and use the [`gh-pr-description`](../gh-pr-description/SKILL.md) skill. Land one coherent PR at a time; after landing, refresh from current `main` and rerun read-only discovery for the next high-confidence batch. ## Handoff Report: - root cause and removed low-value categories; - production owner simplifications; - retained false positives and why they remain valuable; - focused and full proof actually run, with tier timings; - production versus test LOC; - PR and merge state; - named follow-ups. - AGENTS.md (20368 bytes)
# 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 - `examples` — self-contained example agents built against the workspace `eve` - `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, and meaningful behavior changes—not file lists or commit logs. Keep the Summary short and lead with that justification. Follow it with a Changes section: a flat list of the important changes, public API first, each with a short reason only when it is not obvious. Link a prior issue or discussion when one exists, and call out important scope boundaries or preserved behavior. Never include a Validation, Test plan, or Checklist section. 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. When the user explicitly asks to shepherd, land, or merge a PR, or to get one green, use the [`pr-shepherd`](./.agents/skills/pr-shepherd/SKILL.md) skill to run a fresh-context review, address and resolve comments, get CI green, and merge. Do not start it on your own after an implementation or when only asked to open a PR. ## 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 guard:docs-budget # fixes and internal changes don't grow docs (pre-commit and 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 # scenarios that run eve: eve dev, eve start, real files and shells (Turbo builds prerequisites) pnpm test:build # building and packaging apps with eve: framework, production, and packaging builds (Turbo builds prerequisites) pnpm test:public-types # type checks of the published declarations (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`, `rolldown`, and `undici` as its only runtime dependencies. This keeps eve installs as small as possible and avoids exposure to hijacked nested dependencies that are not pinned directly in the main lockfile. eve hands its own `rolldown` to Nitro through `deps.paths` and never lets Nitro resolve or install a package on demand. 6. **Stable APIs follow semantic versioning.** Break a stable public API only in a major release. Prefer additive changes; when a stable API needs an incompatible replacement, ship the replacement beside it, mark the old API `@deprecated`, and remove it in the next major release. The [stability policy](./docs/reference/typescript-api.md#stability-policy) defines which surfaces carry this promise; experimental and internal APIs do not. 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. **Comments document the public API, nothing else.** In `packages/`, the only comments are JSDoc on declarations users can see (what a published entry exports and the types it refers to), tool directives such as `@ts-expect-error`, and license notices (`/*! ... */`, `@license`, `SPDX-License-Identifier`) that credit adapted third-party code. Every published export has JSDoc. Do not add comments while fixing a bug or refactoring; well-named code is the documentation. Express an invariant as code that fails when it breaks: a named assert that throws with the reason in its message, a type, or a `pnpm guard:invariants` rule. Rules 67 and 68 enforce this with no baseline. 11. **Configure Nitro from data.** eve's Nitro host is built from one typed host spec, one ordered plugin list, and one route table. Follow the foundation invariants in [`packages/eve/src/internal/nitro/AGENTS.md`](./packages/eve/src/internal/nitro/AGENTS.md) when touching `internal/nitro/`. Machine-checkable invariants are enforced by `pnpm guard:invariants`, which runs in Vercel CI. If the guard fails, fix the violation rather than editing the baseline — baselines may only shrink. ## Research plans Research documents live in the top-level `research/` directory and require `issue`, `status`, and `last_updated` frontmatter. Keep plans concise and focus primarily on the proposed authoring API and externally observable semantics. Include only the architecture needed to explain boundaries, data flow, and invariants; avoid speculative implementation detail, repeated rationale, and exhaustive task inventories. Use a compact diagram when it makes a lifecycle or ownership relationship materially clearer. ## Testing Use the [`test-audit`](./.agents/skills/test-audit/SKILL.md) skill when writing, reviewing, or pruning tests. Tests belong in one of four tiers. Pick the tightest tier that can express the assertion: - **Unit** (`src/**/*.test.ts`): pure logic, colocated. No filesystem writes, subprocesses, or real network calls. - **Integration** (`src/**/*.integration.test.ts`): multiple modules in memory. - **Scenario** (`src/**/*.scenario.test.ts`, `test/scenarios/`): real subprocess, HTTP port, or bundler. Scenario files run in one of three areas: - running eve (`vitest.scenario.config.ts`): `eve dev` and `eve start` behavior, and small files that need a real filesystem or shell; - building and packaging apps with eve (`vitest.build.config.ts`): the `apps/frameworks` smoke builds (`framework-fixtures`), framework host builds (`framework-builds`), `eve build` and its Nitro and Vercel output (`production-build`), and consumers of the packed tarball and its CLI (`packaging`); - type checks of the published declarations (`vitest.public-types.config.ts`). A new scenario file runs eve unless it is listed in `packages/eve/vitest.scenario-shared.ts`; add build and packaging files there. - **E2E** (`e2e/fixtures/*/evals/`): fixture-owned `eve eval` suites that run only in CI. The model suite (`e2e-local`) runs real matrix models against the local world; the world suites (`e2e-vercel`, …) run deterministic mock models (`EVE_E2E_MODEL=mock`) and exclude `real-model`-tagged evals. See [`e2e/README.md`](./e2e/README.md). Windows CI runs every integration file except those whose first line is `// @linux-only: <reason>`. Mark a file only when none of its tests touches anything Windows can change: filesystem paths and links, file watching, processes and signals, module loading, bundling, the CLI, the dev host, or Workflow's local World on disk. Agent and session behavior compiled from memory, on either host, is the same on every OS. Unmarked files run on Windows. **Running a single file or filtered test: always pass the tier config.** Only the `vitest.<tier>.config.ts` files alias `#*` imports to `./src`; a bare `vitest run <path>` resolves them to compiled `./dist` output, so you end up testing stale builds. Use: ```sh pnpm --filter eve exec vitest run --config vitest.unit.config.ts <path-or-pattern> # or vitest.integration.config.ts / vitest.scenario.config.ts for those tiers, # and vitest.build.config.ts (add --project <name>) / vitest.public-types.config.ts # for the scenario files they run ``` Add `-t "<name>"` to filter by test name. If you touched anything under `#compiled/*`, run `pnpm build:compiled` first — the tier configs do not rebuild it. Do not commit fixture trees under `packages/eve/test/fixtures/` — scenario app content is defined inline as `ScenarioAppDescriptor` objects (CI enforces this). ## End-to-end tests Automated tests cover module-level behavior, but they don't prove a fixture agent boots, accepts a request, and streams a response over HTTP. E2E suites cannot run locally and must run in CI. When a change needs e2e coverage, add or update the relevant fixture eval, then proceed to commit and push. Optionally watch CI for the results and iterate on any failures. Pick the fixture that exercises the surface you changed; if none does, add a new eval under the matching fixture's `evals/` directory. E2E evals must be deterministic and self-contained. Keep e2e free of external service startup and injected env requirements (beyond model-provider credentials). Write model-facing eval prompts as benign, process-oriented narratives. Use neutral named actors such as Alice and Bob, and describe the ordinary workflow that produces the state under test. Avoid terse, adversarial, or probe-like wording when a natural scenario can test the same behavior. Such wording can trigger provider refusals and cause live-model flake. Do not weaken the behavior or security boundary under test. Do not set `VERCEL_TEAM_ID` at build: sandbox template keys must derive identically at build and runtime, and Vercel has no team variable at runtime. The shared Vercel project's Preview env must provide the model-provider credentials the fixtures need. TUI smoke tests live under `packages/eve/test/tui-client` and run with `pnpm test:tui`. See [`e2e/README.md`](./e2e/README.md). ## Templates Keep every template in `apps/templates` on the same versions: - `packageMa - aistorehub.json (383 bytes)
{ "name": "Eve", "slug": "eve", "version": "1.0.0", "type": "agent", "description": "The Open Framework for Building Agents", "owner": "community", "repository": "catalog", "github_repo_url": "https://github.com/vercel/eve", "tags": [ "trending", "typescript", "vercel", "github", "open-source" ], "imported_at": "2026-11-21T23:56:33.478Z" } - apps/docs/AGENTS.md (2240 bytes)
# eve docs app ## Responsive UI All user-facing UI changes must be mobile-responsive. Before completing a UI change, verify it at a narrow mobile viewport and a desktop viewport. Check for page-level horizontal overflow, clipped content, unreadably narrow columns, overlapping controls, and whether dense navigation should wrap or scroll horizontally. ## Geistdocs - Read `node_modules/@vercel/geistdocs/docs/agents.md` and the focused pages under `node_modules/@vercel/geistdocs/docs/pages/` before changing package-backed behavior. - Keep `createGeistdocs` from `@vercel/geistdocs/next` as the `next.config.ts` wrapper. It composes Fumadocs MDX and generates the app-route manifest used by `createProxy`; do not replace it with `createMDX` directly. - Keep `cacheComponents: true` and `partialPrefetching: true` in `next.config.ts`. - Restart `next dev` after adding, deleting, or renaming an App Router page or route so `createGeistdocs` regenerates its route manifest. - Do not export `dynamic`, `dynamicParams`, `revalidate`, or `fetchCache` from App Router pages or route handlers. - Generate every supported root language. Read `[lang]` through `next/root-params` only in Server Components; retain route context `params` in Route Handlers and Server Actions. - Set `prefetch={true}` on app-owned links to statically generated docs, integrations, and templates so navigation reveals the complete destination immediately. - Keep package adapters thin. Do not deep-import package internals or edit generated `.source`, `.next`, or `node_modules` files. <!-- BEGIN:nextjs-agent-rules --> # This is NOT the Next.js you know This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices. This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean. <!-- END:nextjs-agent-rules --> - apps/docs/app/[lang]/agents.md/route.ts (482 bytes)
import { createAgentsRoute } from "@vercel/geistdocs/routes/agents"; import { transformAgentsMarkdown } from "@/lib/geistdocs/agents-transform"; import { config } from "@/lib/geistdocs/config"; const agentsRoute = createAgentsRoute({ config, transform: (markdown, { request }) => transformAgentsMarkdown(markdown, { origin: request.nextUrl.origin, }), }); export const GET = agentsRoute.GET; export const generateStaticParams = agentsRoute.generateStaticParams; - apps/frameworks/next-multi-agent/agents/billing/instructions.md (163 bytes)
You are the billing agent in the Next.js multi-agent fixture. Keep replies to one or two short sentences. Help with invoices, plans, refunds, and payment status.
- apps/frameworks/next-multi-agent/agents/research/instructions.md (178 bytes)
You are the research agent in the Next.js multi-agent fixture. Keep replies to one or two short sentences. Help turn research questions into a clear next step or brief summary.
- apps/templates/eve-agent-python-template/AGENTS.md (20517 bytes)
# eve Agent with Python This repository is a web chat for an eve agent with a Python backend. The agent lives in `agent/`, the Next.js app that serves the chat and the other pages lives in `apps/web/`, and the FastAPI backend lives in `apps/api/`. `vercel.ts` deploys all three as services of one Vercel project. Use Node.js 24, pnpm, and uv. The root `package.json` holds every JavaScript dependency, and `apps/web` has no `package.json` of its own. The backend's Python dependencies are in `apps/api/pyproject.toml` and `apps/api/uv.lock`. These instructions are for agents maintaining the repository. The agent's behavior is defined in [agent/instructions.md](agent/instructions.md) and the tools under `agent/tools/`. ## Project map | Change | Location | | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Agent identity, when to use each tool, and response style | `agent/instructions.md` | | Model and session limits | `agent/agent.ts` | | Tools | `agent/tools/` | | Hooks that react to session events, such as resetting the `render_ui` guard | `agent/hooks/` | | Backend client used by the agent's tools, and shared with the web app | `agent/lib/backend.ts` | | Zod schemas for tasks and Python tool results, shared with the chat's cards | `agent/lib/tasks.ts` and `agent/lib/python-tools.ts` | | Components the agent can render with `render_ui` | `agent/lib/ui-catalog.ts`, rendered by `apps/web/app/_components/ui-registry.tsx`, with sortable tables in `data-table.tsx` and link preview images from `apps/web/app/preview-image.ts` | | HTTP channel and caller auth | `agent/channels/eve.ts` | | Sandbox and its network policy | `agent/sandbox.ts` | | Backend app, routers, and error handlers | `apps/api/main.py` and `apps/api/routers/` | | Database connection and table creation | `apps/api/core/config.py` and `apps/api/core/db.py` | | Task table and request schemas | `apps/api/models/task.py` | | Backend tests | `apps/api/tests/` | | Shared-password tokens, used by the agent and the web app | `apps/web/lib/password-auth.ts` | | Access rule and checks for the web app | `apps/web/lib/auth-mode.ts`, `apps/web/proxy.ts`, and `hasAccess()` in `apps/web/lib/session.ts` | | Sign-in and sign-out | `apps/web/app/login/` | | Backend client for Server Components, Server Actions, and route handlers | `apps/web/lib/backend.ts` | | Backend proxy for client components | `apps/web/app/api/backend/[[...path]]/route.ts` | | Chat layout, composer, and session handling | `apps/web/app/_components/agent-chat.tsx` | | Messages, tool calls, questions, and approvals | `apps/web/app/_components/agent-message.tsx` | | Cards for task and Python tool results | `apps/web/app/_components/tool-cards.tsx` | | Tasks, Backend, and API pages | `apps/web/app/tasks/`, `apps/web/app/backend/`, and `apps/web/app/api-docs/` | | Header, navigation, and page metadata | `apps/web/app/layout.tsx` and `apps/web/components/nav.tsx` | | Theme colors and global styles | `apps/web/app/globals.css` | | Vercel services, routes, and the backend binding | `vercel.ts` | | Python lint and format rules | `[tool.ruff]` in `apps/api/pyproject.toml` | | Setup and customization guidance | `README.md` and `CUSTOMIZATION.md` | `apps/web/components/ui/` and `apps/web/components/ai-elements/` are copies from the shadcn/ui and AI Elements registries, and `pnpm dlx shadcn add` overwrites them. Make template-specific changes in `apps/web/app/`, and edit these folders only to fix a defect. ## Before implementing changes Inspect the relevant implementation first. For eve API changes, start with [the installed documentation index](node_modules/eve/docs/README.md), then read the page it identifies before authoring tools, connections, channels, skills, subagents, schedules, or deployment. Use [eve's published documentation](https://eve.dev/docs) if the installed docs are unavailable. This Next.js version differs from older releases, so read the relevant guide in `node_modules/next/dist/docs/` before changing the web app, as [apps/web/AGENTS.md](apps/web/AGENTS.md) describes. For json-render changes, read the READMEs in `node_modules/@json-render/core`, `node_modules/@json-render/react`, and `node_modules/@json-render/shadcn`. Verify other third-party APIs, including FastAPI, SQLModel, and Pydantic, against the installed package or current official documentation rather than relying on recalled signatures. Keep discovery bounded: read the routed documentation and the files needed for the change, then implement. Follow imports or public types only when they resolve a specific unanswered question. Do not recursively scan `node_modules`, `apps/api/.venv`, or unrelated framework pages. Content-only changes to the agent's instructions do not require framework research. Preserve the configured model unless changing it is part of the request. For a new external integration, check the eve registry before writing one from scratch: ```sh pnpm exec eve registry search <query> --json pnpm exec eve registry view <item> ``` Prefer items whose `implementation` is `native`. When installation is part of the task, use `pnpm exec eve add <item> --non-interactive`. Exit code 2 means setup needs an answer or a prerequisite, so read the final NDJSON event and run its `next.command`. Never pass secrets through `--answer`. ## Implementation conventions Match the comment density and naming of the surrounding file. Add TSDoc where it helps with types or understanding, such as exported functions, components, and props. Document parameters with `@param name - description`, meaningful return values with `@returns`, and thrown errors with `@throws`. eve names each tool after its file, so files in `agent/tools/` use snake_case. When you add, rename, or remove a tool, update the matching section of `agent/instructions.md`, and update `CARD_RENDERERS` in `tool-cards.tsx` if the tool has a card. Keep strict TypeScript, and change the code to satisfy it. The repository has no TypeScript linter or formatter, so follow the formatting of nearby code. Python code follows the Ruff rules in `apps/api/pyproject.toml`, with a line length of 100. `apps/web` imports several `agent/lib/` modules through relative paths, and `agent/channels/eve.ts` imports `apps/web/lib/password-auth.ts`. Keep those boundaries intact: - `agent/lib/tasks.ts`, `agent/lib/python-tools.ts`, and `agent/lib/ui-catalog.ts` load in the browser, so keep them free of eve runtime, backend, and Node.js imports. - `agent/lib/backend.ts` loads in the web app's server code, so keep it free of eve runtime imports. - `apps/web/lib/password-auth.ts` loads in the agent, so keep it free of Next.js imports. The zod schemas in `agent/lib/tasks.ts` and `agent/lib/python-tools.ts` mirror the Pydantic response models in `apps/api/`. Change both sides together, and add or update a backend test. Server Actions run from any route, so each one starts with `hasAccess()` from `apps/web/lib/session.ts`, validates its arguments, and returns `{ error }` instead of throwing, because Next.js hides thrown messages in production. Files marked `"use server"` may export only async functions and types, so put shared helpers in a plain module that imports `server-only`. The web app uses Cache Components with Partial Prefetching. Pages render a static shell and await backend data inside `<Suspense>`, as `apps/web/app/tasks/page.tsx` does. Pages that export `instant = true` ask the dev overlay to flag anything that would block navigation. Code that reads the clock or the request, such as session checks, calls `connection()` first so it never runs during prerendering. Backend routes sit at the root, with no `/api` prefix, because the binding calls the service directly. App endpoints live under `/v1`, and Python tools for the agent live under `/tools`. The backend creates missing tables on its first database request, under a Postgres advisory lock so concurrent instances don't race. Without `DATABASE_URL`, a deployment answers database requests with `503` through `DatabaseNotConfiguredError`. The `httpx2` development dependency is required by FastAPI's test client. ## Access control to preserve - The auth order in `agent/channels/eve.ts` is `passwordAuth`, `vercelOidc()`, then `localDev()`. `passwordAuth` returns `null` when the session cookie is missing or invalid, and eve rejects requests that no check accepts. - `apps/web/lib/password-auth.ts` signs `v1.<expiresAt>` tokens with HMAC-SHA256 keyed on `EVE_CHAT_PASSWORD`, so changing the password revokes every session. Sessions last 30 days, and comparisons run in constant time. Keep the cookie httpOnly, `SameSite=Lax`, and secure in production. - `getAuthMode` returns `local-dev` only under `next dev` or `vercel dev` without a password. Without a password, a deployed app returns `unconfigured` and fails closed. `isAuthorized` is the single access rule that `proxy.ts` and `hasAccess()` share. - The `proxy.ts` matcher excludes whole paths only: `/login` with its subpaths and its RSC and prefetch variants, `_next/static`, `_next/image`, `favicon.ico`, and `icon.svg`. Keep new exclusions anchored so a path such as `/logins` stays gated. - `safeNext` in `apps/web/app/login/actions.ts` allows only same-origin paths after sign-in. - `apps/web/app/preview-image.ts` fetches only https URLs on host names, and its `publicLookup` refuses any host that resolves to a private, loopback, link-local, or reserved address. Keep both checks for every redirect. - The chat checks `/api/auth/status` when the agent responds with a 401, and redirects to `/login` when the web app also answers 401. ## Generated UI to preserve - `uiSpecSchema` in `agent/lib/ui-catalog.ts` validates each elem - apps/templates/eve-agent-python-template/apps/web/AGENTS.md (679 bytes)
<!-- BEGIN:nextjs-agent-rules --> ## This is NOT the Next.js you know This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices. This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean. <!-- END:nextjs-agent-rules -->
- apps/templates/eve-agent-python-template/CLAUDE.md (11 bytes)
@AGENTS.md
- apps/templates/eve-chat-template/AGENTS.md (288 bytes)
# eve Agent App This project uses the eve framework. Before writing code, always read the relevant guide in `node_modules/eve/docs/`. Use `eve` lowercase in user-facing copy, docs, prompts, and comments. Do not title-case it unless it is part of an exact external title or quoted text.
- apps/templates/eve-chat-template/CLAUDE.md (11 bytes)
@AGENTS.md
- apps/templates/eve-coding-agent-template/AGENTS.md (3760 bytes)
# eve Agent App This project uses the eve framework: an agent is a directory of files under `agent/`, and eve compiles and runs it. For a content-only change to the root agent's identity, purpose, tone, or response guidelines, edit its existing authored instructions. Fresh projects use `agent/instructions.md`; a project may instead use `agent/instructions.ts` or files under `agent/instructions/`. You do not need to read the framework docs for a content-only instructions change. A fresh project already has its selected model in `agent/agent.ts`; preserve that file unless the user asks to change the model. ## Read the docs before writing code ```sh ls node_modules/eve/docs ``` Start with `docs/README.md`: it maps each task to the page that covers it. Read that page before authoring tools, connections, channels, skills, subagents, schedules, or deployment. In a workspace or local package install, resolve the installed `eve` package location first. If the package docs are missing, use https://eve.dev/docs. Use a bounded authoring loop: 1. Read the relevant page and inspect only files you will modify or need to imitate. 2. Stop discovery once the file location, imports, and definition shape are clear. Implement the smallest complete behavior the user requested. 3. Run one narrow verification. Expand investigation only when it fails or the request needs project-specific details. Follow links or inspect public types only when the routed page leaves the task unanswered. Do not recursively glob `node_modules`, enumerate the entire docs tree, or read unrelated scaffold files when the direct path is known. Package-manager links can hide files from recursive glob tools even though direct reads work. ## Prefer an existing integration When a task names an external product or service, search the registry before implementing its integration. For a generic capability, author a tool instead. ```sh eve registry search <query> --json eve registry view <item> ``` Prefer items whose `implementation` is `native`; use Chat SDK adapters when no native channel fits. `registry view` links the item's documentation. Install without driving interactive prompts: ```sh eve add <item> --non-interactive ``` Exit code 0 means setup completed, 1 failed, and 2 needs an answer or a prerequisite. On exit 2, run the `next.command` from the final NDJSON event. For a non-secret question, replace its `<JSON value>` answer placeholder with the answer you collected; string values need JSON quotes. Never pass a secret in `--answer`. See `docs/install-integrations.mdx` for setup prerequisites. ## Use eve for Vercel operations Use eve to link and deploy Vercel projects: ```sh eve link --non-interactive --project <name-or-id> [--team <team-id-or-slug>] eve deploy --non-interactive --yes [--project <name-or-id>] ``` A setup may report `eve link` as a prerequisite; run it, then retry the continuation. When a completed setup event has `deploymentRequired: true`, run the `next` command it reports. ## Validate the change Run the validation the task requests. When it does not establish the behavior you changed, run the narrowest relevant check. ## This agent A coding agent built on `eve/extensions/code` and `eve/extensions/git` that works in Slack threads, Slack code channels, and GitHub. Read `node_modules/eve/docs/code-extension.mdx` before changing `agent/extensions/`, `agent/sandbox.ts`, or `agent/lib/github.ts`, and the code channel sections of `node_modules/eve/docs/channels/slack/reference.mdx` before changing `agent/channels/slack.ts`, `agent/lib/code-channel.ts`, or the code channel tools. The `git__gh` tool depends on the Vercel Sandbox network policy, so keep the sandbox on a provider with `setNetworkPolicy()`.
- apps/templates/eve-coding-agent-template/CLAUDE.md (11 bytes)
@AGENTS.md
- apps/templates/eve-computer-use-template/AGENTS.md (618 bytes)
# eve Agent App This project uses the eve framework. Before writing code, read the relevant guide from the installed eve package docs. In most installs, those docs are at `node_modules/eve/docs/`. In workspaces or local package installs, resolve the installed `eve` package location first and read its `docs/` directory. If package docs are unavailable, use https://eve.dev/docs as a fallback. Before implementing an integration yourself, use `eve registry search <query>` or `eve registry list` to discover available integrations. Inspect one with `eve registry view <item>`, then install it with `eve add <item>`.
- apps/templates/eve-computer-use-template/CLAUDE.md (11 bytes)
@AGENTS.md
- apps/templates/eve-content-agent-template/AGENTS.md (8273 bytes)
# AGENTS.md Guidance for AI coding agents working in this repository. ## Project overview A Slack-based content assistant built on the [eve](https://eve.dev) agent framework. Writers @mention it in Slack; it loads a per-surface style **skill**, pulls source material from **Notion** (user-scoped OAuth via Vercel Connect), drafts in the house voice, and publishes approved pieces back to Notion. Files and assets are stored in **Vercel Blob**. The whole agent is defined under `agent/`. eve discovers capabilities from the filesystem. See [`ARCHITECTURE.md`](./ARCHITECTURE.md) for the component map, data flow, and boundaries. ## Setup & commands ```bash pnpm install # install dependencies (Node >= 24) pnpm dev # eve dev — local TUI; run /model once to link 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 pnpm eval:offline # evals/offline on mock models — no model calls, runs in seconds pnpm eval # evals/live on real models (needs Gateway credentials) eve deploy # deploy to Vercel production (use this, not raw `vercel deploy`) npx eve info # print the discovered surface + discovery diagnostics ``` There is no unit-test suite. **Verify changes with `pnpm typecheck` and `npx eve info` (both must report 0 errors / 0 warnings), then run `pnpm eval:offline`, and `pnpm eval` when you have credentials, and exercise the agent in the `pnpm dev` TUI.** The offline evals run the agents on the mock models in `agent/lib/mock-model.ts` (`EVE_MOCK_MODEL=1`) and make no model calls; the live evals call real models, so they need the project's AI Gateway credentials (`vercel env pull` or `/login` in the 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/notion.ts` registers as `notion`. - Authored slots: `agent/agent.ts` (model), `agent/instructions.md` (system prompt), `agent/tools/*.ts` (`defineTool`, or `defineWorkflowTool` for durable tools such as `research`), `agent/connections/*.ts`, `agent/channels/*.ts`, `agent/skills/<name>/SKILL.md`, `agent/memory/<slot>.ts` (`defineMemory`), `agent/subagents/<id>/agent.ts` (`defineAgent`), `agent/sandbox.ts` (exports `environment` and a `defineSandbox()` default). - **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 — pass a policy that inspects `toolName`/`toolInput` to gate specific tools (e.g. `notion` gates `notion-create-pages` via its `APPROVAL_REQUIRED_TOOLS` list). - **Skills** are load-on-demand. A packaged skill (`<name>/SKILL.md`) requires `description` frontmatter; that description is the routing hint. Adding a new surface is just a new `<surface>-style` skill folder: the `SURFACES` enum that `check_style` and the reviewer's `get_surface_rubric` share is generated from those folders into `agent/lib/surfaces.generated.ts` by `pnpm sync:shared`, so there is no hand-edited enum to keep in step. Tool code can't read skill files at runtime, so each skill's `references/banned-words.json` is bundled into `agent/lib/banned-words.generated.ts` by the same script. - **Shared references** live in `shared-references/` (the source of truth). `scripts/sync-shared.mjs` copies them into every skill's `references/` and regenerates the managed `## Shared references` section in each `SKILL.md` (the bullet text lives in that script's `SHARED_FILES`). Edit the source and run `pnpm sync:shared` (also run on `predev`/`prebuild`); never edit the synced copies or that section. A skill's own `## References` section is left untouched. - **Subagents** are declared under `agent/subagents/<id>/agent.ts` (`defineAgent`, required `description` — the routing hint). The directory name is the identity and the lowered tool name (no namespace; it must not collide with a tool name). 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 reviewer carries its own generated rubric module + `get_surface_rubric` tool rather than inheriting the root's skills). Structured output is requested per turn, not on `defineAgent`, so both set `tool: false` and the root reaches them through the `research` / `review` workflow tools, which call `askSubagent` (`agent/lib/subagent.ts`): one `ctx.agent("<id>").send(message, { outputSchema })`. A tool can't share a subagent's name (the compiler rejects it even with `tool: false`), hence the different names. - **Models** are Gateway ids kept in `agent/lib/models.ts`. The researcher's model is routed per call with `auto()` from `eve/models` (a decision model picks from an allowlist using the research message; `fallback` covers decider failures only, and a message over 16,000 characters is rejected). `check_style` asks the same decision model yes/no questions with `decide()` from `eve/ai`, inside a `"use step"` helper so replay reuses the answers. `decide` returns probabilities, not calibrated confidence: treat a mid-range value as "unsure" and fall back to a model that can reason (here, the `reviewer` subagent), and report why the fallback ran. - After editing, **check LSP diagnostics / `pnpm typecheck`** and fix type errors before moving on. ## Code style - Linting and formatting are handled by **Ultracite** (a Biome preset). Run `pnpm check` before finishing and `pnpm fix` to auto-fix. Config is in `biome.jsonc`; the kebab-case filename rule is disabled there because eve tools use snake_case names. - TypeScript strict; ESM with `NodeNext` resolution (relative imports need a `.js` extension). Prefer `const`, arrow functions, optional chaining / nullish coalescing. - Validate tool input/output with `zod` schemas. - `@biomejs/biome` is pinned to 2.5.x: Ultracite 8.0.x's preset still configures a nursery rule that Biome 2.6 renamed, so Biome 2.6 refuses the config. Bump both together once Ultracite supports 2.6 (`pnpm exec ultracite doctor` checks the pairing). - Document exported config with **TSDoc** (`@remarks`, `@param`, `@returns`, `@defaultValue`, `@see`). Avoid inline `//` comments — put rationale in the TSDoc block instead. ## Security - **Never ask the user for API keys, client secrets, or any other credentials.** - **Never commit secrets.** `.env*` is gitignored. Connector UIDs are read from env (`SLACK_CONNECTOR`, `NOTION_CONNECTOR`); Notion auth is per-user via Vercel Connect and Blob auth is via the project's OIDC token — there are no API keys in code. - When building a `RegExp` from data, escape it (literal match) to avoid ReDoS; bound untrusted input length. - Gate irreversible or high-impact actions behind `approval`: destructive tools (`delete_asset`) and connection writes (the `notion` connection gates `notion-create-pages`). - For per-user storage, scope by the resolved principal (`ctx.session.auth.current`), never by model input — see `agent/memory/preferences.ts`, which gives only signed-in writers a memory document. The asset tools refuse the Blob prefixes listed in `agent/lib/reserved-paths.ts`, so they can't read or overwrite a writer's memory. - Give each agent only the built-in tools it needs. The root keeps `read_file` (skills read their references with it) and has `bash`, `write_file`, and `edit_file` disabled; the researcher and the reviewer set `defaultTools: false`, and the researcher adds back only `web_search` and `web_fetch`. ## Before committing - `pnpm typecheck` passes. - `pnpm check` (Ultracite) passes. - `npx eve info` reports 0 errors / 0 warnings. - No secrets, `node_modules`, or build output (`.eve`, `.vercel`, `.output`) staged. - apps/templates/eve-content-agent-template/CLAUDE.md (11 bytes)
@AGENTS.md
- apps/templates/eve-contentful-agent-template/AGENTS.md (12568 bytes)
# eve Contentful Agent This repository is a reusable Slack-based Contentful assistant built on eve. It supports arbitrary Contentful schemas and stores a searchable copy of configured content on Vercel Drives. Use Node.js 24 and pnpm. These instructions are for agents maintaining the repository. The assistant's behavior is defined in [agent/instructions.md](agent/instructions.md) and the dynamic instructions under `agent/instructions/`. ## Project map | Change | Location | | --- | --- | | Assistant behavior and writing guidelines | `agent/instructions.md` | | Contentful context and current time | `agent/instructions/` | | Model and session limits | `agent/agent.ts` | | Tool definitions | `agent/tools/` | | Contentful configuration and implementation | `agent/lib/contentful/` | | Publication approvals | `agent/tools/publish_contentful_entry.ts` and `agent/lib/contentful/publication*.ts` | | Slack channel and shared integration code | `agent/channels/slack.ts` and `agent/lib/integrations/slack/` | | Slack tables and charts | `agent/lib/tools/` and `agent/lib/integrations/slack/visualizations/` | | Search and query procedures | `agent/skills/` | | Content copied to Vercel Drives | `agent/lib/contentful/mirror/` and `agent/schedules/` | | Local and hosted sandbox selection | `agent/sandbox.ts` | | Per-user writing preferences | `agent/memory/user-preferences.ts` and `agent/lib/memory/scope.ts` | | Setup and customization guidance | `README.md`, `CUSTOMIZATION.md`, and `.env.example` | Keep this template independent of the original internal content agent. Do not add organization-specific space IDs or content types to application code. Team membership restrictions are an optional extension described in `CUSTOMIZATION.md`; they are not enabled by default. ## Before implementing changes Inspect the relevant implementation and nearby tests. For eve API changes, start with [the installed documentation index](node_modules/eve/docs/README.md), then read the page it identifies for the task. Use [eve's published documentation](https://eve.dev/docs) if the installed docs are unavailable. Verify third-party APIs against the installed package or current official documentation rather than relying on recalled signatures. Keep discovery bounded: read the routed documentation and the files needed for the change, then implement. Follow imports or public types only when they resolve a specific unanswered question. Do not recursively scan dependencies or read unrelated framework pages. Content-only changes to the assistant's instructions do not require framework research. Preserve the configured model unless changing it is part of the request. For a new external integration, check the eve registry before writing an integration from scratch: ```sh pnpm exec eve registry search <query> --json pnpm exec eve registry view <item> ``` Prefer native integrations. When installation is part of the task, use `pnpm exec eve add <item> --non-interactive`. Exit code 2 means setup needs an answer or prerequisite; inspect the final NDJSON event and follow its continuation instructions. Never pass secrets through `--answer`. ## Implementation conventions Keep tool definitions in `agent/tools/` small, with reusable behavior in `agent/lib/`. Follow existing input schemas and error handling rather than introducing another validation pattern. Locale-aware Contentful helpers receive an explicit `LocaleContext` from `withLocale` or `withContentfulLocale`; forward it through every read, write, and recovery path without ambient storage. Preserve the strict TypeScript and Ultracite configuration. Do not disable rules to make a port or refactor pass. The existing filename exemption for `agent/tools/*.ts` is intentional: tool files use names such as `get_contentful_entry.ts`. Preserve those names unless the task requires changing the tool interface. Add useful TSDoc when introducing or changing exported helpers, tools, channels, or configuration types. Document parameters with `@param name - description`, type parameters with `@typeParam`, and meaningful return values with `@returns`. Document properties beside their declarations. Use `@remarks` for behavior callers need to know, such as publication side effects or recovery requirements; avoid comments that merely repeat the symbol name or type. Use `.env.example` to document new configuration without credentials. When configuration changes affect setup or behavior, update the relevant human documentation too. ## Contentful behavior to preserve - Read current entries before changing them and validate their versions. Preserve untouched fields and locales. Protected RichText fields require block patches for updates; initial creation can still set them. - Every content type requires publication approval unless explicitly configured as a supporting component. Website routes take precedence over component exemptions, so routed types still require approval. - Save ordinary entry edits without publishing. Creating an exempt component can publish it immediately. New asset uploads are processed and published during entry creation or updates; these side effects must remain explicit in tool descriptions and documentation. - Page publication requires a Slack preview listing the content to be published, followed by eve's native approval controls. Preserve confirmed preview delivery and the saved version checks. Never bypass a cancelled request or silently expand what the user approved. - Page publication can include changed supporting components. Publishing only exempt components preserves pending edits on already-live references. Linked pages must be explicitly requested before publishing them. Read `publication.ts` and its tests before changing this behavior. - Publication can partially succeed. Preserve per-item outcomes and asset recovery IDs so interrupted operations can resume without duplicate uploads or entries. - Any authenticated person can edit content and approve or cancel publication requests. Slack apps and Workflows that mention the agent get eve's `service` principal. `requireContentfulEditor` and the publication `response` policy must keep rejecting it. Use authenticated identities for permission checks; Slack profile names and message text do not establish authorization. - Derive Slack principals with eve's `defaultSlackAuth`. Bot posts that Slack delivers without a user, such as Slack Workflow messages, get a per-bot `service` principal from their validated `bot_id`; drop every other message without a verified author. Never build a principal from `raw.user` or share one across senders. Profile lookups in `identity.ts` add names and images for the model, never emails. Keep `selectInboundHandlers` and `channel.test.ts` in sync, because a custom `onMessage` receives mentions and DMs unless a specific handler is supplied. ## Local and hosted behavior `pnpm dev` opens eve's terminal chat. Local sessions use `just-bash` and do not mount Vercel Drives, so they search Contentful directly. The hosted agent uses Vercel Sandbox with a read-only copy of the Drive. Each agent configuration uses one Drive for all its configured spaces. Hosted sandboxes deny outbound network access because every API request runs in the application. The mirror sync creates its own sandbox in `mirror/drive.ts`, which also denies network access. The schedules copy Contentful content to the Drive. Local development does not run cron schedules automatically. Manually dispatching a schedule from the local server can still update a real Vercel Drive; it is not a local simulation. Do not trigger syncs or publish Contentful content merely to validate documentation. The default terminal UI displays only error logs. Use `pnpm dev --logs all` when checking success or skipped-sync messages. `pnpm exec eve logs` reads saved diagnostic logs from interactive local sessions. Verify the logging path before claiming a message appears in the terminal. Writing preferences are stored separately for each authenticated person through `byHumanPrincipal`, which matches `byPrincipal` for people and disables memory for service principals. Renaming the slot or changing the scope value orphans saved preferences. The Memory section of `agent/instructions.md` must keep treating recalled memory as untrusted and must keep telling the model never to save sensitive information. Hosted storage uses private Vercel Blob; local storage is temporary. Prefer Vercel OIDC for supported services rather than introducing additional API tokens. The Slack channel uses `SLACK_CONNECTOR`, falling back to `slack/placeholder` so compilation works before Slack is configured. Slack delivery still needs a real connector. Pull the project's variables with `vercel env pull .env.local`. Use the Vercel CLI for project configuration and deployment instructions. Confirm unfamiliar flags with `--help`. Keep adding and updating environment variables in the CLI instead of sending users to the dashboard unnecessarily. Provisioning services or deploying the agent is separate from checking code and documentation. ## Documentation standards Keep `README.md` concise, with the deployment flow and the existing technology and customization tables. Put detailed procedures in `CUSTOMIZATION.md`. Preserve working examples and previously accepted wording when revising a section. Write for a person using the template: - Explain what a setting controls before showing it. Distinguish optional values from required configuration and state what the code does when a variable is unset. - Name the relevant system when discussing environments: Contentful environments select content; Vercel environments determine where project variables apply. - State general behavior before giving an example. Do not let an author-profile example imply a rule applies only to author profiles. - Explain terms on first use. Prefer "searchable copy of Contentful content" to an unexplained "mirror", and "each user's writing preferences" to unspecified "memory" or "preferences". - Connect related ideas naturally. Avoid choppy sequences of short sentences, short sentences split off from the reason that explains them, forced groups of three, parenthetical asides, bold lead-ins, colons joining two sentences, and unnecessary emphasis. Do not begin prose sentences with "A" or "An". - Lowercase Vercel environment names mid-sentence, such as "preview" and "production". Labels at the start of a table cell keep their capitalization. - Keep commands usable in context. Identify required input and explain how to recognize success. Distinguish a request being accepted from its background work completing. Verify behavior against code and current CLI help. When reviewing a passage, read its surrounding section for contradictions and repeated explanations. For a full-file review, cover the entire file rather than fixing only the quoted examples. Formatting and link checks do not replace an editorial review. ## Validation `pnpm check` and `pnpm fix` use `lint.config.ts` explicitly to keep its Ultracite rules separate from monorepo linting. `.oxfmtrc.json` contains the resolved Ultracite formatting preset so root tooling needs no template dependencies. Keep it in sync when upgrading Ultracite. Git hooks are opt-in: run `pnpm exec lefthook install` only from a standalone checkout, never from the eve monorepo. Choose checks that establish the changed behavior. Existing tests live beside their implementations under `agent/`; shared test helpers are under `agent/lib/testing/` and `agent/lib/contentful/testing/`. | Command | Purpose | | --- | --- | | `pnpm check` | Formatting and lint rules | | `pnpm fix` | Apply formatting and lint fixes | | `pnpm typecheck` | TypeScript checks | | `pnpm exec vitest run <test-file>` | Tests for the changed behavior | | `pnpm validate` | Formatting, lint, types, all tests, and unused-code checks | | `pnpm exec eve info` | Agent diagnostics | | `pnpm build` | Production compilation | For code changes, run the relevant tests and static checks. Use `pnpm validate` for changes spanning several parts of the agent, and run `pnpm build` when changing framework registration or build behavior. Add tests for meaningful behavior changes, especially publication rules and recovery paths. For documentation-only changes, check formatting and affected links or examples. Do not run the full application test suite for a prose edit. State which checks ran and distinguish source inspection from behavior tested against live services.
- apps/templates/eve-contentful-agent-template/CLAUDE.md (11 bytes)
@AGENTS.md
- apps/templates/eve-data-analyst-template/AGENTS.md (20007 bytes)
# eve Data Analyst This repository is a reusable Slack-based data analyst built on eve. It answers questions by exploring a Postgres database, applying the team's metric definitions, and running read-only SQL as the asking person's database role. Use Node.js 24 and pnpm. These instructions are for agents maintaining the repository. The analyst's behavior is defined in [agent/instructions.md](agent/instructions.md), the skills under `agent/skills/`, and the dynamic instructions under `agent/instructions/`. ## Project map | Change | Location | | --- | --- | | Analyst behavior, answer format, visualization rules, memory rules, and response style | `agent/instructions.md` | | Metric definitions and SQL conventions | `agent/skills/metric-definitions.md` and `agent/skills/sql-style.md` | | Current time and reporting time zone context | `agent/instructions/current-time.ts` | | Model and session limits | `agent/agent.ts` | | Warehouse tools | `agent/tools/run_sql.ts` and `agent/tools/describe_schema.ts`, implemented in `agent/lib/tools/` | | Configuration, role resolution, SQL safety, and Postgres access | `agent/lib/analyst/` | | Cost-based approval and its Slack card | `agent/lib/analyst/approval.ts` and `agent/lib/analyst/approval-card.ts` | | Thread role guard, which keeps query results with the role that fetched them | `agent/hooks/thread-role-guard.ts`, implemented in `agent/lib/analyst/thread-role-guard.ts` and `agent/lib/analyst/thread-roles.ts`, with the Slack notice in `agent/lib/integrations/slack/replies.ts` | | Slack charts and tables | `agent/tools/post_slack_*.ts`, implemented in `agent/lib/tools/` and `agent/lib/integrations/slack/visualizations/` | | Folded "SQL query" section on Slack answers | `agent/lib/analyst/query-log.ts` and `agent/lib/analyst/sql-attachment.ts`, attached by `agent/lib/integrations/slack/replies.ts` and `visualizations/post.ts` | | Memory slots and scopes | `agent/memory/` and `agent/lib/memory/scope.ts` | | Slack channel, sender auth, profile lookups, and input requests | `agent/channels/slack.ts` and `agent/lib/integrations/slack/` | | HTTP channel and caller auth | `agent/channels/eve.ts` | | Built-in tool overrides | `agent/tools/web_fetch.ts` and `agent/tools/web_search.ts` | | Local and hosted sandbox selection | `agent/sandbox.ts` | | Deploy-time database setup (`vercel-build` and `pnpm db:setup`) | `scripts/setup-on-deploy.ts` and `scripts/setup-on-deploy/plan.ts` | | Demo data, manual role setup, and health checks | `scripts/seed.ts`, `scripts/seed/`, `scripts/setup-sql.ts`, and `scripts/doctor.ts` | | Model-in-the-loop evals | `evals/` | | Shared test fixtures | `agent/lib/testing/` | | Setup and customization guidance | `README.md`, `CUSTOMIZATION.md`, and `.env.example` | Keep the template focused on answering questions from Postgres. Optional integrations, such as Stripe or PostHog connections, are documented in `CUSTOMIZATION.md` and not installed by default. ## Before implementing changes Inspect the relevant implementation and nearby tests. For eve API changes, start with [the installed documentation index](node_modules/eve/docs/README.md), then read the page it identifies for the task. Use [eve's published documentation](https://eve.dev/docs) if the installed docs are unavailable. Verify third-party APIs, including `pg`, against the installed package or current official documentation rather than relying on recalled signatures. Keep discovery focused: read the routed documentation and the files the change needs, then implement. Content-only changes to the instructions or skills need no framework research. Preserve the configured model unless changing it is part of the request. For a new external integration, check the eve registry before writing one from scratch: ```sh pnpm exec eve registry search <query> --json pnpm exec eve registry view <item> ``` Prefer native integrations. When installation is part of the task, use `pnpm exec eve add <item> --non-interactive`. Exit code 2 means setup needs an answer or a prerequisite, so read the final NDJSON event and follow its next command. Pass secrets as environment variables, keeping `--answer` for non-secret values. ## Implementation conventions Keep files in `agent/tools/` to one-line re-exports, with behavior in `agent/lib/`. The filename exemption for `agent/tools/*.ts` in `lint.config.ts` exists because eve names tools after their files. Modules the setup scripts import run under Node's built-in type stripping, so they and everything they import must use `#lib/...` or `#scripts/...` imports and erasable TypeScript syntax only. This covers `agent/lib/analyst/` (except `approval*.ts` and `thread-role*.ts`), `agent/lib/json.ts`, `agent/lib/slack-ids.ts`, `agent/lib/slack-text.ts`, `agent/lib/values.ts`, and `scripts/`. Eval files follow eve's docs and use `.js` specifiers for relative imports. Parse database rows at the boundary with Zod before using them, as `agent/lib/analyst/postgres.ts` does, and test Postgres behavior through the `postgres.connect` seam with the fake client in `agent/lib/testing/postgres.ts`. Keep the strict TypeScript and Ultracite configuration, and change the code to satisfy its rules. The only override beyond the tool filenames allows sequential awaits in `scripts/`, where statements must run in order. Add useful TSDoc when introducing or changing exported helpers, tools, channels, scopes, or configuration types. Document parameters with `@param name - description`, type parameters with `@typeParam`, and meaningful return values with `@returns`. Use `@remarks` for behavior callers need to know. Document new configuration in `.env.example` and `CUSTOMIZATION.md` without credentials, and add it to the Zod schema in `agent/lib/analyst/config.ts` so every problem is reported at once. ## SQL safety to preserve Each layer below works on its own, so keep every one of them complete: - `withReadOnly` opens `BEGIN TRANSACTION READ ONLY`, then sets `statement_timeout`, `ROLE`, `search_path`, and `TIME ZONE` with `SET LOCAL`, and always rolls back. It destroys the connection when the rollback fails. Connections are pooled, so every setting stays `SET LOCAL`. - Model-authored SQL only runs through `wrapQuery`, as `SELECT * FROM (<sql>) AS eve_q LIMIT n`, with `queryMode: "extended"`. The wrapper rejects writes and data-modifying CTEs, and the extended protocol rejects stacked statements. - `normalizeSql` removes only a final semicolon and the whitespace and comments after it. The plan check and the run both wrap the same normalized text, so every other layer still applies to exactly what runs. - The approval policy and `runReadOnlySql` both plan the exact wrapped query with `EXPLAIN (VERBOSE, FORMAT JSON)` and refuse plans that call `set_config` or functions that run SQL text. Those are the `*_to_xml` family, `ts_stat`, `ts_rewrite`, `dblink`, and the contrib functions `crosstab`, `connectby`, and `xpath_table`. A psql check confirmed that, without this, a role could read another granted role's tables through `set_config('role', ...)` plus `query_to_xml`. The SQL text these functions run can be assembled at runtime, so only the function names can be matched. The same check refuses session-level advisory locks, which would outlive the rollback on a pooled connection, `pg_sleep`, and the functions that cancel or end other sessions. Keep both checks and extend `FORBIDDEN_CALL` in `agent/lib/analyst/sql.ts` when Postgres or an installed extension adds similar functions. The list can't cover user-defined functions that run dynamic SQL, so separate logins per role, or revoking `set_config` from `PUBLIC`, remain the complete fix. - Only validated values are interpolated into SQL: role names through `identifierSchema`, schema names through `schemaNameSchema`, integers from the config schema, and time zones through `isTimeZone`. Everything else is a bind parameter. `schemaNameSchema` differs only by allowing `public`, which stays reserved as a role name. `db:seed` still refuses `public`, because it replaces the schema it loads. - `resolveAnalystRole` reads `ANALYST_ROLE_MAP` with `Object.hasOwn` on a null-prototype map. Keys are full principal IDs, bare Slack member IDs, or Slack channel IDs, taken only from the verified Slack webhook attributes of a Slack user principal. Precedence is a personal denial under either the full principal ID or the bare Slack user ID, then the current channel's role, then the personal role, where the full principal ID wins over the bare ID, then the default. Principal IDs shaped like bare Slack user or channel IDs are never looked up directly. Service, runtime, and anonymous callers get access only through an entry for their own principal ID, and channel roles apply to people only. Update `access.test.ts` with any change. - The thread role guard records the caller's role in session state after every successful `run_sql` or `describe_schema` result. Its `turn.started` hook cancels a turn whose caller resolves to a different role or to no access. The Slack `turn.settled` renderer for cancelled turns in `replies.ts` runs the same check and posts the "start a new thread" notice. It can't rely on a marker from the hook, because state a hook writes just before `ctx.cancel()` isn't kept. Roles are recorded by tool name through `ROLE_SCOPED_TOOLS` in `thread-roles.ts`, so renaming either tool file without updating that list silently turns the guard off. `local-dev` and callers who share a role are never blocked. Update `thread-roles.test.ts` and `thread-role-guard.test.ts` with any change. - `run_sql` keeps `approval: { request: requestRunSqlApproval, response: respondToRunSqlApproval }` as an inline object literal, because eve compiles the `approval` property from source and treats a bare identifier as a policy function. The request policy fails closed with a denial carrying the Postgres error. Errors that `isWarehouseUnavailable` recognizes, such as a failed connection, a failed `SET LOCAL ROLE`, or a server shutdown, tell the model to stop and tell the person. Every other error tells it to fix the SQL. The response policy admits only the asking principal when it is a person or `local-dev`. - The agent always queries as the read-only login. It reads `DATABASE_URL` only to derive the `eve_analyst` login's connection with `deriveAnalystUrl`, and only when `ANALYST_DATABASE_URL` is unset. Keep `derivePassword`, `loginUrl`, and the login name in `agent/lib/analyst/derived-login.ts` shared between the deploy step, `scripts/setup-sql.ts`, and the agent. `derivePassword` uses only the owner's password and refuses a `DATABASE_URL` without one. `scripts/seed.ts` refuses to run against `ANALYST_DATABASE_URL`. Every tool stays read-only. - `web_fetch` and `web_search` stay disabled, and `agent/sandbox.ts` blocks outbound network access when deployed, so query results stay in the conversation. ## SQL attachment behavior to preserve - The SQL shown in Slack comes from `recordQuery` in `run_sql`'s `execute`, after the query succeeded, so the section always matches what ran. - The instructions tell the model that the section is attached for it, so its replies leave out SQL. Change the two together. - The attachment keeps the reply's fallbacks: `replies.ts` posts through `postCompletedSlackReply` with the SQL repeated in the Markdown fallback, and `visualizations/post.ts` adds it to the text fallback when it fits. That fallback comes from `sqlAttachmentMrkdwn`, which uses `escapeMrkdwnCode` from `agent/lib/slack-text.ts` to escape mrkdwn and break runs of three or more backticks with zero-width spaces so the SQL can't close its code block. After a block rejection, `post.ts` retries with the SQL as plain blocks from `sqlAttachmentPlainBlocks`, skipping that step for size errors, then posts the visualization alone, then text only. Whenever the delivered message can't show the SQL, it posts the SQL as its own text message and ignores that message's failure, because the tool ends the turn and no final reply follows. A renderer that takes over the final reply owns its delivery, so let errors propagate to eve's delivery notice and post each reply once. ## Deploy-time setup to preserve - `vercel-build` runs `scripts/setup-on-deploy.ts` before `eve build`. It does nothing when `ANALYST_DATABASE_URL` is set, or when `DATABASE_URL` is unset or has no password. Otherwise it loads demo data only when `ANALYST_SEED_DEMO_DATA` is on and the demo schema is missing or older than a week, and replaces only schemas the seed created. - A failed demo reload is logged, and the role setup still runs. - It catches every error and exits successfully, so deploys always complete and the agent reports unfinished setup in Slack. - Setup grants the base role `USAGE`, `SELECT` on existing tables, and default privileges only in `ANALYST_SHARED_SCHEMAS`, which defaults to `ANALYST_SCHEMAS` and must be a subset of it. It grants and revokes nothing in the other `ANALYST_SCHEMAS` schemas, because team roles inherit the base role. Discovery in `agent/lib/analyst/postgres.ts` filters on `has_schema_privilege` and `has_table_privilege`, so each person sees only tables their role can query. `resolveSchemaLists` in `agent/lib/analyst/schemas.ts` resolves the two lists, including the demo schema, for `parseAnalystConfig`, `planDeploySetup`, and `scripts/setup-sql.ts`, so keep all three using it. Each caller validates the names itself. - `loadDemoData` builds the new data, grants, and planner statistics in `eve_demo_staging` inside one transaction. It then drops the seed's own tables by name and the live schema with the default `RESTRICT`, and renames the staging schema into place under `lock_timeout`, retrying from a savepoint. Postgres checks dependencies under the drop's locks, so anything added to the schema or depending on it during the load stops the swap. `replacementBlocker` only refuses early with a clearer reason. Only `db:seed --force` drops with `CASCADE`. Live demo tables stay readable during the load. The marker table and schema comment move with the rename, so `replacementBlocker` keeps working. When a table leaves `DEMO_TABLES`, keep its name in the lists that `inspectDemoSchema` and `dropDemoSchemaStatements` use, or existing demo schemas refuse every reload until someone runs `db:seed --force`. - `pnpm db:doctor` judges demo data freshness by `_eve_demo_seed.anchor_at` and `DEMO_DATA_MAX_AGE_MS` from `scripts/setup-on-deploy/plan.ts`, the same rule the deploy uses to reload it. - The deploy step creates the pg `Client` inside the `try`, with `connectionTimeoutMillis` and an `error` listener, because its constructor parses `DATABASE_URL` and reads certificate files. `scripts/setup-on-deploy.test.ts` runs the script as a child process and checks that it exits successfully. - Keep code, messages, and test fixtures provider-neutral, with generic wording and `example.com` hosts. ## Metric and memory behavio - apps/templates/eve-data-analyst-template/CLAUDE.md (11 bytes)
@AGENTS.md
- apps/templates/eve-discord-agent-template/AGENTS.md (288 bytes)
# eve Agent App This project uses the eve framework. Before writing code, always read the relevant guide in `node_modules/eve/docs/`. Use `eve` lowercase in user-facing copy, docs, prompts, and comments. Do not title-case it unless it is part of an exact external title or quoted text.
- apps/templates/eve-discord-agent-template/CLAUDE.md (11 bytes)
@AGENTS.md
- apps/templates/eve-mem0-template/AGENTS.md (3169 bytes)
# eve Agent App This project uses the eve framework: an agent is a directory of files under `agent/`, and eve compiles and runs it. For a content-only change to the root agent's identity, purpose, tone, or response guidelines, edit its existing authored instructions. Fresh projects use `agent/instructions.md`; a project may instead use `agent/instructions.ts` or files under `agent/instructions/`. You do not need to read the framework docs for a content-only instructions change. A fresh project already has its selected model in `agent/agent.ts`; preserve that file unless the user asks to change the model. ## Read the docs before writing code ```sh ls node_modules/eve/docs ``` Start with `docs/README.md`: it maps each task to the page that covers it. Read that page before authoring tools, connections, channels, skills, subagents, schedules, or deployment. In a workspace or local package install, resolve the installed `eve` package location first. If the package docs are missing, use https://eve.dev/docs. Use a bounded authoring loop: 1. Read the relevant page and inspect only files you will modify or need to imitate. 2. Stop discovery once the file location, imports, and definition shape are clear. Implement the smallest complete behavior the user requested. 3. Run one narrow verification. Expand investigation only when it fails or the request needs project-specific details. Follow links or inspect public types only when the routed page leaves the task unanswered. Do not recursively glob `node_modules`, enumerate the entire docs tree, or read unrelated scaffold files when the direct path is known. Package-manager links can hide files from recursive glob tools even though direct reads work. ## Prefer an existing integration When a task names an external product or service, search the registry before implementing its integration. For a generic capability, author a tool instead. ```sh eve registry search <query> --json eve registry view <item> ``` Prefer items whose `implementation` is `native`; use Chat SDK adapters when no native channel fits. `registry view` links the item's documentation. Install without driving interactive prompts: ```sh eve add <item> --non-interactive ``` Exit code 0 means setup completed, 1 failed, and 2 needs an answer or a prerequisite. On exit 2, run the `next.command` from the final NDJSON event. For a non-secret question, replace its `<JSON value>` answer placeholder with the answer you collected; string values need JSON quotes. Never pass a secret in `--answer`. See `docs/install-integrations.mdx` for setup prerequisites. ## Use eve for Vercel operations Use eve to link and deploy Vercel projects: ```sh eve link --non-interactive --project <name-or-id> [--team <team-id-or-slug>] eve deploy --non-interactive --yes [--project <name-or-id>] ``` A setup may report `eve link` as a prerequisite; run it, then retry the continuation. When a completed setup event has `deploymentRequired: true`, run the `next` command it reports. ## Validate the change Run the validation the task requests. When it does not establish the behavior you changed, run the narrowest relevant check.
- apps/templates/eve-mem0-template/CLAUDE.md (11 bytes)
@AGENTS.md
- apps/templates/eve-memory-agent-template/AGENTS.md (10507 bytes)
# eve Memory Agent This repository is a reusable Slack-based assistant built on eve that saves the preferences people share with it. User preferences and channel conventions are stored in separate memory slots and recalled before the agent responds to each message. Use Node.js 24 and pnpm. These instructions are for agents maintaining the repository. The assistant's behavior is defined in [agent/instructions.md](agent/instructions.md) and the dynamic instructions under `agent/instructions/`. ## Project map | Change | Location | | --- | --- | | Assistant behavior, memory rules, and response style | `agent/instructions.md` | | Current time context | `agent/instructions/current-time.ts` | | Model and session limits | `agent/agent.ts` | | Memory slots | `agent/memory/user-preferences.ts` and `agent/memory/channel-preferences.ts` | | Channel memory scope | `agent/lib/memory/scope.ts` | | Slack channel, sender auth, and profile lookups | `agent/channels/slack.ts` and `agent/lib/integrations/slack/` | | HTTP channel and caller auth | `agent/channels/eve.ts` | | Built-in tool overrides | `agent/tools/` | | Local and hosted sandbox selection | `agent/sandbox.ts` | | Shared test fixtures | `agent/lib/testing/` | | Setup and customization guidance | `README.md`, `CUSTOMIZATION.md`, and `.env.example` | Keep the template focused on memory. Features such as Slack tables, charts, or approval cards belong in a project built from the template, not in the template itself. Optional extensions, such as shared reference files on Vercel Drives, are documented in `CUSTOMIZATION.md` and are not enabled by default. ## Before implementing changes Inspect the relevant implementation and nearby tests. For eve API changes, start with [the installed documentation index](node_modules/eve/docs/README.md), then read the page it identifies for the task. Memory changes usually need `node_modules/eve/docs/memory/`. Use [eve's published documentation](https://eve.dev/docs) if the installed docs are unavailable. Verify third-party APIs against the installed package or current official documentation rather than relying on recalled signatures. Keep discovery bounded: read the routed documentation and the files needed for the change, then implement. Follow imports or public types only when they resolve a specific unanswered question. Do not recursively scan dependencies or read unrelated framework pages. Content-only changes to the assistant's instructions do not require framework research. Preserve the configured model unless changing it is part of the request. For a new external integration or memory provider, check the eve registry before writing an integration from scratch: ```sh pnpm exec eve registry search <query> --json pnpm exec eve registry view <item> ``` Prefer native integrations. When installation is part of the task, use `pnpm exec eve add <item> --non-interactive`. Exit code 2 means setup needs an answer or prerequisite; inspect the final NDJSON event and follow its continuation instructions. Never pass secrets through `--answer`. ## Implementation conventions Keep files in `agent/tools/` small, with reusable behavior in `agent/lib/`. The template's tool files only disable eve built-ins. Disabling `write_file` steers the model toward the memory tools. The web and delegation tools are removed because a memory agent doesn't need them and they would give planted instructions a way to send data out. `bash` and `read_file` stay enabled for the Drives extension, and `agent/sandbox.ts` denies outbound network access when deployed. The filename exemption for `agent/tools/*.ts` in `lint.config.ts` exists because eve matches built-in tools by filename. Preserve the strict TypeScript and Ultracite configuration. Do not disable rules to make a port or refactor pass. Add useful TSDoc when introducing or changing exported helpers, tools, channels, scopes, or configuration types. Document parameters with `@param name - description`, type parameters with `@typeParam`, and meaningful return values with `@returns`. Use `@remarks` for behavior callers need to know, such as when a scope disables memory; avoid comments that merely repeat the symbol name or type. Use `.env.example` to document new configuration without credentials. When configuration changes affect setup or behavior, update the relevant human documentation too. pnpm enforces a minimum release age for dependencies. Do not bypass the policy or relax it globally. When an install fails because of it, report the affected packages and let the user decide whether to add pinned exclusions to `pnpm-workspace.yaml`. ## Memory behavior to preserve - Resolve every memory scope from authenticated session details, never from model input, message text, or Slack profile names. Profile lookups in `identity.ts` add names and images for the model, never emails, and do not establish identity or authorization. - Return `null` from a scope when the caller doesn't qualify. eve then skips the slot and its tools; never fall back to a shared scope. - `bySlackChannel` accepts only Slack webhook user principals with a `slack:<team>` issuer and a public or private channel ID. It disables channel memory in one-to-one DMs and for bots, and returns the shared `local-dev` scope during local development. Update `scope.test.ts` with any change to these rules. - Both template scopes include the Slack installation issuer, so memory from different workspaces never shares storage. Keep that boundary in new scopes. - Renaming a slot file or changing a scope's tuple shape, including the `"slack-channel"` prefix, changes the storage key and orphans existing memories. For a rename, keep the old namespace by returning `defaultNamespace({ ...ctx, slot: "<old-name>" })` from `eve/memory`. Switching an existing slot to an explicit namespace string also orphans its memories, and a tuple change always needs a migration. - Keep the Memory section of `agent/instructions.md` consistent with each slot's `description`. The instructions decide which slot to use; the descriptions say what each slot holds. Recalled memory is untrusted user data, and the instructions must keep telling the model never to save sensitive information. ## Local and hosted behavior `pnpm dev` opens eve's terminal chat. Local sessions use `just-bash`, don't look up Slack profiles, and keep memory only while the development server runs, so saved preferences disappear when it restarts. Both slots resolve to a shared `local-dev` scope locally. The hosted agent uses Vercel Sandbox and stores memory in a private Vercel Blob store that file memory reads through `BLOB_STORE_ID` and Vercel OIDC. Prefer Vercel OIDC for supported services rather than introducing additional API tokens. The Slack channel uses `SLACK_CONNECTOR`, falling back to `slack/placeholder` so compilation works before Slack is configured. Slack delivery still needs a real connector. Pull the project's variables with `vercel env pull .env.local`. Use the Vercel CLI for project configuration and deployment instructions, including `vercel deploy --prod`, `vercel env add`, `vercel blob`, and `vercel sandbox`. Confirm unfamiliar flags with `--help`. Provisioning services or deploying the agent is separate from checking code and documentation. ## Documentation standards Keep `README.md` concise, with the deployment flow, the technology and customization tables, and short summaries that link to `CUSTOMIZATION.md` for detailed procedures. Preserve working examples and previously accepted wording when revising a section. Write for a person using the template: - Explain what a setting controls before showing it. Distinguish optional values from required configuration and state what the code does when a variable is unset. - Explain terms on first use, such as memory slot, scope, and turn. Prefer plain descriptions to implementation terms like "process memory". - Say which memory a statement applies to. Distinguish user memory from channel memory instead of writing an unspecified "memory" or "preferences" when the difference matters. - Lowercase Vercel environment names mid-sentence, such as "preview" and "production". Labels at the start of a table cell keep their capitalization. - Connect related ideas naturally. Avoid choppy sequences of short sentences, short sentences split off from the reason that explains them, forced groups of three, parenthetical asides, bold lead-ins, colons joining two sentences, and unnecessary emphasis. Do not begin prose sentences with "A" or "An". - Keep commands usable in context. Identify required input and explain how to recognize success. Verify behavior against code and current CLI help. When reviewing a passage, read its surrounding section for contradictions and repeated explanations. After applying an edit, check that the revision didn't introduce new problems from the list above. Formatting and link checks do not replace an editorial review. ## Validation `pnpm check` and `pnpm fix` use `lint.config.ts` explicitly to keep its Ultracite rules separate from monorepo linting. `.oxfmtrc.json` contains the resolved Ultracite formatting preset so root tooling needs no template dependencies. Keep it in sync when upgrading Ultracite. Git hooks are opt-in: run `pnpm exec lefthook install` only from a standalone checkout, never from the eve monorepo. Choose checks that establish the changed behavior. Tests live beside their implementations under `agent/`. | Command | Purpose | | --- | --- | | `pnpm check` | Formatting and lint rules | | `pnpm fix` | Apply formatting and lint fixes | | `pnpm typecheck` | TypeScript checks | | `pnpm exec vitest run <test-file>` | Tests for the changed behavior | | `pnpm validate` | Formatting, lint, types, all tests, and unused-code checks | | `pnpm exec eve info` | Agent diagnostics | | `pnpm build` | Production compilation | For code changes, run the relevant tests and static checks. Use `pnpm validate` for changes spanning several parts of the agent, and run `pnpm build` when changing memory slots, channels, the sandbox, or other framework registration. Add tests for meaningful behavior changes, especially scope rules. For documentation-only changes, check formatting and affected links or examples. Typecheck new code samples before adding them to the docs. Do not run the full application test suite for a prose edit. State which checks ran and distinguish source inspection from behavior tested against live services. - apps/templates/eve-memory-agent-template/CLAUDE.md (11 bytes)
@AGENTS.md
- apps/templates/eve-slack-agent-template/AGENTS.md (135 bytes)
# Eve Agent App This project uses the eve framework. Before writing code, always read the relevant guide in `node_modules/eve/docs/`.
- apps/templates/eve-slack-agent-template/CLAUDE.md (11 bytes)
@AGENTS.md
- apps/templates/eve-software-factory-template/AGENTS.md (16630 bytes)
# AGENTS.md Guidance for AI coding agents working in this repository. ## Project overview The eve Software Factory template: Foreman, an orchestrator agent built on the [eve](https://eve.dev) framework that turns work items into reviewed draft pull requests on the configured repository (`FACTORY_REPO`). Work arrives from GitHub (an issue labeled `factory` can run unattended once, guarded by a persistent private Blob claim; retries require a trusted explicit @mention; @Foreman mentions from API-verified writers on `FACTORY_REPO` run attended) and from Linear Agent Sessions. The orchestrator triages every item with `triage_work_item` (one decision-model call, no side effects). Clarification uses the **classifier** station to write questions; questions and confirmed duplicates stop without building. Actionable changes run **analyst** (plan + acceptance criteria, own repo checkout) → **implementer** (codes, verifies, pushes a feature branch from its own checkout) → **reviewer** (independent verdict on the pushed branch, different model vendor, max 2 revision cycles). HTTP tickets arrive through a dedicated bearer-only intake API with permanent private claims; these unattended sessions have no GitHub comment thread and cannot relabel, close, or reopen issues or PRs. The orchestrator then opens a draft PR; marking it ready parks on human approval, closing or reopening issues runs as reversible triage, and merging is not in the tool surface. Per-user preferences live in **Vercel Blob**, alongside a shared, per-repo **factory brain** (durable notes about the target repository) under a reserved Blob prefix, readable by every run but writable only by trusted callers, and **handoff artifacts**: long Markdown documents (research memos, analysis detail) that stations pass to each other by id under the reserved `artifacts/` prefix instead of inlining them through the orchestrator. The pipeline lives in `agent/instructions.ts`. The whole agent is defined under `agent/`. eve discovers capabilities from the filesystem. See [`ARCHITECTURE.md`](./.github/ARCHITECTURE.md) for the component map, data flow, trust model, and boundaries. ## Setup & commands ```bash pnpm install # install dependencies (Node 24.x) pnpm dev # eve dev — local TUI; run /model once to link 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 pnpm eval # eve eval — run the evals suite (see tags below; costs real tokens) eve deploy # deploy to Vercel production (use this, not raw `vercel deploy`) npx eve info # print the discovered surface + discovery diagnostics pnpm discovery # strict eve info --json diagnostic check, no cloud credentials pnpm test # offline auth, storage, sandbox, Git, intake, and triage regressions (includes *.scenario.test.ts) pnpm test:git-transfer # focused real local Git push-authority and isolation regressions pnpm validate # check + typecheck + test + discovery ``` **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.** The evals suite (`pnpm eval --tag fast`) guards routing and safety behavior; `pnpm eval pipeline/full-pipeline` runs the whole line and pushes a real branch, so run it deliberately and against a scratch repo. ## 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/agent.ts` is the tool `agent`; a connection at `agent/connections/linear.ts` registers as `linear`; a subagent directory `agent/subagents/classifier/` lowers into the tool `classifier`. - Authored slots: `agent/agent.ts` (model + session budget), `agent/instructions.ts` (`defineInstructions`, the orchestrator prompt; resolved at build time, injecting `FACTORY_REPO`), `agent/tools/*.ts` (`defineTool`), `agent/connections/*.ts`, `agent/extensions/*.ts`, `agent/channels/*.ts`, `agent/skills/<name>/SKILL.md`, `agent/subagents/<id>/agent.ts` (`defineAgent`), per-agent `sandbox.ts`. - **Model assignments are centralized** in `agent/lib/models.ts` (the `MODELS` map). Every `agent.ts` reads its entry from there (`model: MODELS.<agent>`) instead of hardcoding a gateway id, so a model swap is a one-line edit in that file. One split is deliberate: `implementer` runs the strongest coding model on a different vendor than `reviewer`, so the review stays independent; keep those two on different vendors. - **Extensions:** `agent/extensions/<ns>.ts` mounts a prebuilt eve extension; the filename is the namespace and its tools appear to the model as `<ns>__<tool>` (here: `github__*` from `@github-tools/eve-extension`). Config keys (`include`, `requireApproval`) use bare tool names. - **Channels:** `github` (eve GitHub channel via Vercel Connect, botName resolved from the connector's app slug; `onComment` keeps the mention/ignore rules, resolves the canonical `FACTORY_REPO` identity, verifies sender write permission via GitHub, and stamps repository-bound trust; `onIssue` accepts `labeled` events whose current labels include `factory`, verifies the sender holds at least triage permission, and atomically claims `issue-intake/<lowercase-owner>/<lowercase-repo>/<issue-number>.md` before unattended dispatch; published eve does not expose the changed label, so an unrelated label on an unclaimed factory issue can initiate its first run; claims are permanent, storage failures fail closed, and requeue or clarification requires a trusted explicit @mention (see README for delivery limitations); `onCheckSuite` dispatches only for failed suites on API-verified open draft `factory/*` PRs whose exact head matches the report and whose head/base repository IDs match the configured repository; reserved ticket heads never dispatch, and revisions require explicit trusted GitHub/Linear intake. CI uses a distinct `github-ci-webhook` authenticator with server-stamped PR/head/repository scope, permitting only exact-head pushes while the PR remains an open draft and comments on that PR, never labels, close/reopen, new PRs, or marking ready. The broker rechecks after import as its final lookup immediately before push. The fix loop is capped by counting attempt comments on the PR thread and typed CI diagnosis before code revisions; `onPullRequest` never dispatches; public summaries need a separate restricted agent), `linear` (Agent Sessions; only identified members of `LINEAR_WORKSPACE_ID` are accepted and stamped trusted), plus the `eve` route-auth channel. - **Subagents are the stations.** Declared under `agent/subagents/<id>/`; `description` is required (the routing hint) and each station sets `tool: false`, since `defineAgent` no longer carries an `outputSchema`. A `defineWorkflowTool` at `agent/tools/run_<id>.ts` is what the orchestrator actually calls: it blocks on `ctx.agent(id).send(message, { outputSchema })` and then `response.result()`, rejecting failed/cancelled/empty results through `stationOutput`, attaching the schema from `agent/lib/stations/schemas.ts` per call. The wrapper can't share the station's own name (`run_classifier`, not `classifier`): eve's compiler rejects a tool and a local subagent with the same public identity, `tool: false` notwithstanding. A declared subagent runs in a fresh child session and inherits no capabilities from the root (no instructions, skills, connections, tools, or sandbox), but eve forwards the parent's current auth to each child message. The orchestrator packs work-item context into the `message`, and any capability a station needs lives in the station's own directory (its `sandbox.ts`, its `tools/`). Long documents travel between stations as **handoff artifacts**: the researcher and analyst save them with `save_artifact`, downstream stations open them with `read_artifact`, and the orchestrator relays only the id (the factories live in `agent/lib/artifacts/`). - **Approval-gated tools must not live inside a station.** A declared subagent can request input, but nothing is watching a station's own card, so a station tool that returned `user-approval` would strand the run. Anything needing approval belongs on the root (the `github` extension); station side effects must be inert by construction, like `push_branch` (one validated factory feature ref, actual default/protected branches refused, authenticated transfer in a fresh disposable sandbox). - **`agent/lib/trust.ts` is the single trust authority.** Channels stamp trust at dispatch; approval policies in `agent/lib/github/approval.ts` read the stamps and return `not-applicable` / `user-approval` / `denied`. A new capability never invents its own caller check; gate on the existing predicates. - **Station sandboxes** share their environment and init logic via `agent/lib/github/repo-sandbox.ts` (`createFactoryEnvironment`, `factoryInit`): each station's `defineSandbox(...)` opens that environment, then `factoryInit` clones the factory repository and runs `FACTORY_SETUP_COMMAND`, once per session. All authenticated Git runs in a fresh disposable transfer sandbox through `agent/lib/github/git-transfer.ts`; only bounded object bundles enter a station. The GitHub channel's built-in credentialed checkout is disabled. Every environment (root included) passes the shared `FACTORY_SANDBOX_CREATE_OPTIONS` from that module: Git/pnpm preparation keyed by a tooling digest, one kept snapshot, and a 14-day expiration. Every live `open()` uses `factoryOpenOptions()` for exact-host egress restrictions. Initialization disables automatic npm/pnpm/Yarn install scripts before setup unless `FACTORY_ALLOW_INSTALL_SCRIPTS=1`; these package-manager defaults are not a security boundary. Remote operations target the literal URL with firewall-brokered credentials only in the isolated transfer sandbox; no station ever receives a credentialed policy. - **Tools** run in the app runtime (full `process.env`), one default export per file; station git tools run their commands in the station's sandbox via `ctx.getSandbox(environment)`, importing that station's own `environment` export from its `sandbox.ts` (the bare `ctx.getSandbox()` handle has no `setNetworkPolicy`). Gate destructive root tools with `approval` from `eve/tools/approval` (here: `clear_user_preferences`), or with a trust policy from `agent/lib/github/approval.ts` when the gate depends on the caller (here: `update_factory_brain`, gated by `factoryBrainPolicy` so unattended runs can't write shared context). - **Connections** are MCP servers: `linear` (`https://mcp.linear.app/mcp`, app-scoped auth shared through `linearAuth` in `agent/lib/constants.ts`). Its connection-wide `approval` predicate denies all tools, including reads, except trusted member sessions from the configured `LINEAR_WORKSPACE_ID`. - **Skills** are load-on-demand. A packaged skill (`<name>/SKILL.md`) requires `description` frontmatter; that description is the routing hint. The skills here are `writing-quality`, `triaging-issues`, and `github-linear-bridging`. Skills are per-agent: stations don't see the root's skills. - **Evals** live in `evals/` (`defineEval`, one file per case; `evals.config.ts` holds run-wide config; `t.judge` uses eve's default evaluation model, `typesafe-ai/jev`). Category directories are the failure taxonomy (`routing/`, `safety/`, `pipeline/`); `helpers.ts` carries the shared write-tool list so read-only evals assert deny-by-default (`notCalledTool` over the whole list). Tags: `fast` (cheap loop), `slow`, `needs-connect` (asserts calls that must succeed against real Connect auth), `pipeline` (pushes a real branch; opt-in). - After editing, **check LSP diagnostics / `pnpm typecheck`** and fix type errors before moving on. ## Code style - Linting and formatting are handled by **Ultracite** (a Biome preset). Run `pnpm check` before finishing and `pnpm fix` to auto-fix. Config is in `biome.jsonc`; the kebab-case filename rule is disabled there because eve tools use snake_case names. - TypeScript strict; ESM with `NodeNext` resolution (relative imports need a `.js` extension). Prefer `const`, arrow functions, optional chaining / nullish coalescing. - Validate tool input/output with `zod` schemas. - Prose in markdown files is not hard-wrapped: write each paragraph or bullet as one line. - Agent-facing text (instructions, skill bodies, tool and subagent descriptions) follows the "How you write" rules in `agent/instructions.ts`: no em dashes, no machine-made words, no bold for emphasis. It carries behavior only, never framework plumbing (how approvals render, sign-in flows) or references to tools and skills the reading agent can't access — station instructions especially, since stations see none of the root's surface. ## Security - **Never ask the user for API keys, client secrets, or any other credentials.** - **Never commit secrets.** `.env*` is gitignored. Connector UIDs are read from env (`GITHUB_CONNECTOR`, `LINEAR_CONNECTOR`); GitHub and Linear auth is brokered by Vercel Connect (tokens resolved per call, never exposed to the model) and Blob auth is via the project's OIDC token. `FACTORY_REPO` is required at module load (`requireEnv`), so a missing value fails discovery; `FACTORY_SETUP_COMMAND` is optional. - **Git safety is structural; keep it that way.** Authenticated Git must run in a new transfer VM, never a station or station-derived snapshot. Import only object bundles, never environment, configuration, hooks, executables, or processes. Use the literal factory URL, clean environment and Git configuration, explicit refspec, and disabled hooks. `pushBranch` also verifies the actual default branch and protection through GitHub, enforces the factory prefix, and never force-pushes. Do not restore the default GitHub channel checkout or station-wide credential policies. - **Respect the trust model.** Trust is stamped at dispatch by the channels; unattended runs are denied writes (except labels, comments scoped to their stamped intake issue, close/reopen, and draft PRs) rather than parked. When adding a tool or connection, pick its policy from `agent/lib/github/approval.ts` (or the trust predicates) instead of hardcoding `"never"`. - If you ever build a `RegExp` from data, escape it (literal match) and bound the input length. - Gate irreversible or high-impact actions behind `approval` (here: `clear_user_preferences`, plus the ship-gate policies on the GitHub extension). - Every reserved Blob prefix is declared in the namespace registry in `agent/lib/blob.ts`, alongside the shared read/write/delete document helpers all Blob tools go through. Any general-purpose Blob tool added later must consult the registry's guards before acting, so a managed document can't be reac - apps/templates/eve-software-factory-template/CLAUDE.md (11 bytes)
@AGENTS.md
- apps/templates/eve-sre-agent-template/AGENTS.md (2539 bytes)
# AGENTS.md Guidance for AI coding agents working in this repository. ## Project overview **sre** is a Slack incident response agent built on [eve](https://eve.dev). It pulls evidence from Datadog, GitHub, Slack, and Vercel. The agent lives under `agent/`. ## Setup & commands When the user asks you to set up the project, follow [`docs/setup-for-agents.md`](./docs/setup-for-agents.md). You are already at the repo root. Do not use the Deploy button. When the user asks for automated investigations, follow [`docs/automate-investigations.md`](./docs/automate-investigations.md) only after Slack replies work. ```bash pnpm install # Node 24.x (see .nvmrc) pnpm dev # eve TUI; run /model once to link a provider pnpm typecheck # tsc (TypeScript, no emit) pnpm check # ultracite (Biome) lint + format check pnpm fix # ultracite (Biome) auto-fix pnpm test # agent/**/*.test.ts pnpm validate # check + typecheck + eve info pnpm exec eve deploy # production deploy; do not use raw vercel deploy --prod ``` ## Code style - Linting and formatting are handled by **Ultracite** (a Biome preset). Run `pnpm check` before you finish. Run `pnpm fix` to auto-fix. Config is in `biome.jsonc`. The kebab-case filename rule is off because eve tools use snake_case names. - TypeScript is strict. The project uses ESM with `NodeNext` resolution. Relative imports use a `.ts` extension (`allowImportingTsExtensions`). Prefer `const`, arrow functions, optional chaining, and nullish coalescing. - Validate tool input and output with `zod` schemas. - Do not hard-wrap prose in markdown files. Write each paragraph or bullet as one line. ## Security - Never ask the user to paste secrets into chat. - The user sets secrets with `vercel env add` or the Vercel project env UI. Never read `.env` files. - Never commit secrets. `.env*` is gitignored. `.env.example` is the exception. - Connector UIDs come from env (`SLACK_CONNECTOR`, `GITHUB_CONNECTOR`, `DATADOG_CONNECTOR`). Auth is brokered by Vercel Connect. Tokens are resolved per call and are not exposed to the model. - `WEBHOOK_SECRET` is a shared secret for `POST /v1/investigate`. Do not put it in chat, commits, or logs. - If you build a `RegExp` from data, escape it for a literal match and bound the input length. ## Before committing - `pnpm validate` passes (Ultracite check, `tsc`, and `eve info` with 0 errors / 0 warnings). - No secrets, `node_modules`, or build output (`.eve`, `.vercel`, `.output`) staged.
- apps/templates/eve-sre-agent-template/CLAUDE.md (42 bytes)
Read and follow [AGENTS.md](./AGENTS.md).
- apps/templates/eve-sre-agent-template/docs/setup-for-agents.md (5280 bytes)
--- title: Set up the sre incident investigation agent (eve) with the Vercel CLI description: Manual end-to-end setup. Create and link the Vercel project, wire connectors and storage, deploy with eve, then verify Slack. --- ## Prerequisites - The user is logged into the Vercel CLI (`vercel whoami` succeeds). - `pnpm` is installed. - Node 24 is active (see `.nvmrc`). ## Main procedure 1. Install dependencies: ```bash pnpm install ``` 2. Determine which teams the user has access to. Then, ask the user for a project name (suggest a sensible default like `sre`) and which team they'd like to use before creating and linking the project: ```bash vercel project add <project-name> --scope <team> vercel project update <project-name> --framework eve --scope <team> vercel link --project <project-name> --scope <team> --yes ``` 3. Link the project with eve: ```bash pnpm exec eve link --project <project-name> --team <team> --non-interactive ``` 4. Create the connectors. Code reads connector UIDs from env, with defaults in `agent/lib/constants.ts` that match `vercel connect create … --name sre`: | Env | Default | Used for | | ---------------------- | ------------- | ----------------------------- | | `SLACK_CONNECTOR` | `slack/sre` | Slack channel and bot Web API | | `GITHUB_CONNECTOR` | `github/sre` | GitHub tools extension | | `DATADOG_CONNECTOR` | `datadog/sre` | Datadog MCP (access token) | | `SRE_VERCEL_CONNECTOR` | `vercel/sre` | Vercel MCP (user OAuth) | <!--AGENTS: please pause and mention this before proceeding--> - When setting up the GitHub connector, instruct the user to prefer checking "readonly" on the permissions for maximum security. - When provisioning Datadog, instruct the user to generate either a [PAT](https://docs.datadoghq.com/account_management/personal-access-tokens/) or [SAT](https://docs.datadoghq.com/account_management/service-access-tokens/). Prefer read-only permissions. Run the Datadog command yourself in an interactive terminal: it prompts for the token. Do not pass the token to an agent or put it in a command argument. ```bash vercel connect create slack --name sre --triggers vercel connect create github --name sre vercel connect create datadog --connection-method access-token --name sre vercel connect create mcp.vercel.com --connection-method mcp --name sre vercel connect list ``` The Slack connector turns on `message.channels`, `channels:history`, `message.groups`, and `groups:history` by default. Channel watch uses those events and scopes. The history and thread read tools also verify the caller's workspace and conversation membership with `auth.test` and `conversations.members`. Ensure the Slack app has the membership scopes for each conversation type it reads (`channels:read`, `groups:read`, `im:read`, and `mpim:read`), then reinstall or reconnect it after permission changes. These tools fail closed when membership cannot be verified and do not permit service-triggered investigations to use the bot's read access. Use the UID printed by each `vercel connect create` command for its attachment. Prefer read-only permissions on the GitHub install. If a connector UID differs from the defaults above, set the matching env var on the project: ```bash vercel env add <CONNECTOR_ENV> production,preview,development --value <connector-uid> --no-sensitive --yes ``` If the Datadog organization is not on the default US site, set `DD_SITE` on the project. Examples are `datadoghq.eu` and `us5.datadoghq.com`. The default is `datadoghq.com`. The Vercel MCP connector uses the requesting Slack user's Vercel authorization. It is unavailable to automated webhook and channel-watch investigations because they use service identities. 5. Provision storage: ```bash vercel blob create-store <project-name>-blob --access private --yes ``` If that store name already exists, choose an unused suffix such as `<project-name>-blob-2`. 6. Pull env locally: ```bash vercel env pull ``` 7. Deploy with eve. Do not use raw `vercel deploy --prod` alone, because eve wraps it: ```bash pnpm exec eve deploy ``` 8. Verify Slack. Ask the user to invite the Slack app into a channel and `@mention` the bot. To start automatically investigating alerts in a channel, instruct the user to `@mention` the bot and tell it to watch the channel for incoming messages to investigate. ## Automate investigations as a follow-up Do not set up automated investigations to start. Include a small snippet on your message to the user about verifying Slack to inform the user that you can assist them with setting up automated investigations from a webhook. When they do, follow [`automate-investigations.md`](./automate-investigations.md). 1. Ask the user to set production `WEBHOOK_SECRET` to a long random value. A portable generator is `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`. The user enters the secret. 2. Redeploy so that the runtime reads the value. 3. Configure the caller to use `POST /v1/investigate`. 4. Invite the bot to each target Slack channel. 5. Send a test request and confirm the `202` response and Slack investigation. ## Security Never write secrets into files, commits, or logs. - apps/templates/eve-tanstack-start-template/AGENTS.md (12068 bytes)
# eve TanStack Start This repository is a reusable web chat for an eve agent. The agent lives in `agent/`, and the TanStack Start app that serves the chat lives in `apps/web/`. `vercel.ts` deploys both as services of one Vercel project. Use Node.js 24 and pnpm. The root `package.json` holds every dependency, and `apps/web` is a pnpm workspace package with none of its own. These instructions are for agents maintaining the repository. The agent's behavior is defined in [agent/instructions.md](agent/instructions.md) and the tools under `agent/tools/`. ## Project map | Change | Location | | --- | --- | | Agent identity, when to use each tool, and response style | `agent/instructions.md` | | Model and session limits | `agent/agent.ts` | | Tools | `agent/tools/` | | Hooks that react to session events, such as resetting the `render_ui` guard | `agent/hooks/` | | Components the agent can render with `render_ui` | `agent/lib/ui-catalog.ts`, rendered by `apps/web/app/_components/ui-registry.tsx`, with sortable tables in `data-table.tsx` and link preview images from `apps/web/app/preview-image.ts` | | HTTP channel and caller auth | `agent/channels/eve.ts` | | Shared-password tokens, used by the agent and the web app | `agent/lib/access.ts` | | Sandbox and its network policy | `agent/sandbox.ts` | | Access checks and sign-in for the web app | `apps/web/app/access.ts`, the `beforeLoad` check in `apps/web/app/routes/__root.tsx`, and `apps/web/app/routes/login.tsx` | | Chat layout, composer, header, home page, and keyboard shortcuts | `apps/web/app/_components/agent-chat.tsx` | | Messages, tool cards, questions, approvals, and authorization prompts | `apps/web/app/_components/agent-message.tsx` | | Routes | `apps/web/app/routes/` | | Theme colors and global styles | `apps/web/app/globals.css` | | `vercel dev` routing fix | `apps/web/app/start.ts` | | Vercel services and routes | `vercel.ts` | | Lint and format rules | `lint.config.ts` and `.oxfmtrc.json` | | Unused-code checks | `knip.json` | | Setup and customization guidance | `README.md` and `CUSTOMIZATION.md` | `apps/web/components/ui/` and `apps/web/components/ai-elements/` are copies from the shadcn/ui and AI Elements registries. `pnpm dlx shadcn add` overwrites them, and lint ignores them. Make template-specific changes in `apps/web/app/`, and edit these folders only to fix a defect. ## Before implementing changes Inspect the relevant implementation first. For eve API changes, start with [the installed documentation index](node_modules/eve/docs/README.md), then read the page it identifies before authoring tools, connections, channels, skills, subagents, schedules, or deployment. Use [eve's published documentation](https://eve.dev/docs) if the installed docs are unavailable. For json-render changes, read the READMEs in `node_modules/@json-render/core`, `node_modules/@json-render/react`, and `node_modules/@json-render/shadcn`. Verify other third-party APIs against the installed package or current official documentation rather than relying on recalled signatures. Keep discovery bounded: read the routed documentation and the files needed for the change, then implement. Follow imports or public types only when they resolve a specific unanswered question. Do not recursively scan `node_modules` or read unrelated framework pages. Content-only changes to the agent's instructions do not require framework research. Preserve the configured model unless changing it is part of the request. For a new external integration, check the eve registry before writing one from scratch: ```sh pnpm exec eve registry search <query> --json pnpm exec eve registry view <item> ``` Prefer items whose `implementation` is `native`. When installation is part of the task, use `pnpm exec eve add <item> --non-interactive`. Exit code 2 means setup needs an answer or a prerequisite, so read the final NDJSON event and run its `next.command`. Never pass secrets through `--answer`. Use eve for the Vercel operations you run, such as `pnpm exec eve link --non-interactive --project <name-or-id>` and `pnpm exec eve deploy --non-interactive --yes`. When a completed setup event has `deploymentRequired: true`, run the `next` command it reports. ## Implementation conventions Write no inline code comments. Add TSDoc only where it helps with types or understanding, such as exported functions, components, constants, and props. Document parameters with `@param name - description`, meaningful return values with `@returns`, and thrown errors with `@throws`. TSDoc can't document destructured props as `@param props.name`, so write `@param props - The component props.` and add TSDoc to each field of the props type. eve names each tool after its file, so files in `agent/tools/` use snake_case. The `unicorn/filename-case` exemption for `agent/tools/**` in `lint.config.ts` exists for that reason. Keep the strict TypeScript and Ultracite configuration, and change the code to satisfy its rules. The configuration makes these exceptions: - `func-style`, `no-use-before-define`, and `react/function-component-definition` are off, so modules use top-down `function` declarations. - `shadcn/no-restyle` contracts allow spacing and typography on the questionnaire components used for question cards. - `typescript/only-throw-error` allows throwing a `Response`, which TanStack Router's `throw redirect(...)` does. Add a new exception only when the code can't reasonably satisfy the rule, and scope it to the files that need it. `knip.json` sets the entry points for the agent and the web app, and ignores the generated route tree and the registry copies. Knip can't read CSS imports, so a package imported only from CSS, such as the Geist fonts and `tw-animate-css`, goes in its `ignoreDependencies`. `apps/web` imports `agent/lib/access.ts` and `agent/lib/ui-catalog.ts` through relative paths. Keep both modules free of React and browser APIs. When you add, rename, or remove a tool, update the Tools section of `agent/instructions.md` to match. When the shadcn CLI adds a component, it may write dependencies to `apps/web/package.json`. Move any needed dependency to the root `package.json`, restore `apps/web/package.json` to its `name`, `private`, and `type` fields, and run `pnpm install`. ## Access control to preserve - The auth order in `agent/channels/eve.ts` is `vercelOidc()`, `localDev()`, `accessCookieAuth()`, then `placeholderAuth()`. `accessCookieAuth()` returns `null` when `EVE_ACCESS_PASSWORD` is unset, so `placeholderAuth()` reports the missing configuration. It throws `UnauthenticatedError` with code `access_required` for a missing, invalid, or cross-site cookie. - `agent/lib/access.ts` derives the signing key from the password, signs HS256 tokens with a `visitor:<uuid>` subject, and compares passwords in constant time. Keep the cookie httpOnly, `SameSite=Lax`, and secure outside development. - `getAccessStatus` returns `open` only in development without a password. Production without a password returns `unconfigured`. - `safeRedirect` allows only same-origin paths after sign-in. - The chat redirects to `/login` when the agent responds with a 401, through `useSignInRedirect` in `agent-chat.tsx`. ## Generated UI to preserve - `uiSpecSchema` in `agent/lib/ui-catalog.ts` validates each element's props against its component, which the catalog's own schema doesn't. The `render_ui` tool uses it as its input schema, and the chat parses tool calls with it before rendering. - The `render_ui` tool description lists every component's description and props, and names the components that accept children. Catalog descriptions are written for the model. - `uiSpecSchema` also rejects a `ResultCard` that isn't a child of a `CardRow`, so result cards always render as a scrolling row. - Every catalog component needs a renderer in `ui-registry.tsx`, which TypeScript enforces through `defineRegistry`. - The model tends to repeat UI contents in its text reply. Three places guard against it: the Response style section of `agent/instructions.md` limits the reply to one sentence when `render_ui` runs, the tool description says the same, and the tool's result reminds the model that the person can already see the UI. Keep all three when changing any of them. - The reply after `render_ui` must be one sentence, never empty, or the model may call `render_ui` again. `render_ui` records the turn it ran in with `lastRenderedTurn` in `agent/lib/ui-state.ts` and rejects a second call in the same turn. The hook in `agent/hooks/reset-render-guard.ts` resets the guard when the person sends a message or answers a question or approval, since eve keeps the same turn open across that input. ## Local and hosted behavior `pnpm dev:app` starts `vercel dev`, which runs both services and routes `/eve/v1/*` to the agent. `pnpm dev:agent` opens eve's terminal chat. During local development, `localDev()` accepts every request, and the chat opens without a password when `EVE_ACCESS_PASSWORD` is unset. Local sessions use `just-bash`, which runs in process with no network isolation, and deployed sessions use Vercel Sandbox with outbound network access denied. Don't start dev servers yourself. Ask the person to run them and report what they see. When writing deployment instructions for people, use the Vercel CLI, including `vercel link`, `vercel env add`, `vercel env pull .env.local`, and `vercel deploy --prod`. Confirm unfamiliar flags with `--help`. Provisioning services or deploying the agent is separate from checking code and documentation. ## Documentation standards Keep `README.md` concise, with the setup flow, the technology and customization tables, and short summaries that link to `CUSTOMIZATION.md` for detailed procedures. Preserve working examples and previously accepted wording when revising a section. Write for a person using the template: - Name the kind of thing on first use, such as "the `EVE_ACCESS_PASSWORD` environment variable" or "the `render_ui` tool", and say what it controls before showing it. State what happens when a value is unset. - Explain terms on first use. Prefer plain descriptions to implementation terms. - Frame guidance positively. Say what to do and what happens, such as "Deploy with `vercel deploy --prod`, which keeps your `.env.local` file as it is." - Connect related ideas naturally, and keep introductions to the essentials. Leave out filler and stock phrases such as "seamless", "robust", and "leverage", along with em dashes, "not just X but Y", forced groups of three, parenthetical asides, bold lead-ins, colons joining two sentences, and sentences beginning with "A" or "An". - Bold exact UI labels, such as **New chat**. Use inline code for files, commands, identifiers, environment variables, and values. - Lowercase Vercel environment names mid-sentence, such as "preview" and "production". - Keep commands usable in context. Identify required input and explain how to recognize success. Verify behavior against the code and current CLI help, and reread each section as a whole for contradictions and repetition. ## Validation Choose checks that establish the changed behavior. | Command | Purpose | | --- | --- | | `pnpm check` | Formatting and lint rules | | `pnpm fix` | Apply formatting and lint fixes | | `pnpm typecheck` | TypeScript checks for the agent and the web app | | `pnpm build` | Production build of the agent and the web app, which needs an AI Gateway credential | | `pnpm build:agent` | Production build of the agent, which needs an AI Gateway credential | | `pnpm build:web` | Production build of the web app | | `pnpm knip` | Unused files, exports, and dependencies | | `pnpm validate` | Formatting, lint, types, and unused-code checks | Run `pnpm validate` after every code change. Run `pnpm build:web` when changing styles, routes, or dependencies of the web app. For documentation-only changes, run `pnpm check`, which also checks Markdown formatting, and apply fixes with `pnpm fix`. State which checks ran and what remains untested in a browser.
- apps/templates/eve-tanstack-start-template/CLAUDE.md (11 bytes)
@AGENTS.md
- apps/templates/eve-vercel-drives-starter/AGENTS.md (10508 bytes)
# eve Vercel Drives Starter This repository is a reusable Slack-based assistant built on eve that reads and saves a team's files on a Vercel Drive. Each session mounts a read-only snapshot of the Drive, and writes go through a short-lived sandbox that holds the Drive's read-write mount. Use Node.js 24 and pnpm. These instructions are for agents maintaining the repository. The assistant's behavior is defined in [agent/instructions.md](agent/instructions.md). ## Project map | Change | Location | | --- | --- | | Assistant behavior and response style | `agent/instructions.md` | | Model and session limits | `agent/agent.ts` | | Drive name, region, mount path, path validation, and writes | `agent/lib/drive.ts` | | Session sandbox and the Drive snapshot mount | `agent/sandbox.ts` | | Save tool and built-in tool overrides | `agent/tools/` | | Upload command | `scripts/upload-to-drive.ts` and `scripts/lib/upload.ts` | | Sample files for the first upload | `content/` | | Slack channel, sender auth, and profile lookups | `agent/channels/slack.ts` and `agent/lib/integrations/slack/` | | HTTP channel and caller auth | `agent/channels/eve.ts` | | Shared test fixtures | `agent/lib/testing/` | | Setup and customization guidance | `README.md`, `CUSTOMIZATION.md`, and `.env.example` | Keep the template focused on reading and saving Drive files. Delete tools, scheduled syncs, approval gates, and additional Drives are documented in `CUSTOMIZATION.md` and are not enabled by default. ## Before implementing changes Inspect the relevant implementation and nearby tests. For eve API changes, start with [the installed documentation index](node_modules/eve/docs/README.md), then read the page it identifies for the task. Sandbox and mount changes usually need `node_modules/eve/docs/sandbox/vercel.mdx`. Use [eve's published documentation](https://eve.dev/docs) if the installed docs are unavailable. Verify Drive behavior against the installed `@vercel/sandbox` types and the [Vercel Drives documentation](https://vercel.com/docs/sandbox/concepts/drives) rather than relying on recalled signatures. Keep discovery bounded: read the routed documentation and the files needed for the change, then implement. Follow imports or public types only when they resolve a specific unanswered question. Do not recursively scan dependencies or read unrelated framework pages. Content-only changes to the assistant's instructions do not require framework research. Preserve the configured model unless changing it is part of the request. For a new external integration, check the eve registry before writing an integration from scratch: ```sh pnpm exec eve registry search <query> --json pnpm exec eve registry view <item> ``` Prefer native integrations. When installation is part of the task, use `pnpm exec eve add <item> --non-interactive`. Exit code 2 means setup needs an answer or prerequisite; inspect the final NDJSON event and follow its continuation instructions. Never pass secrets through `--answer`. ## Implementation conventions Keep files in `agent/tools/` small, with reusable behavior in `agent/lib/`. `save_to_drive.ts` is the only authored tool; the other tool files disable eve built-ins. Disabling `write_file` steers the model toward `save_to_drive`. `web_fetch` and `web_search` are removed because they run in the app outside the sandbox's network policy and would give instructions planted in Drive files a way to send file contents out. `bash` and `read_file` stay enabled for reading `/drive`. The filename exemption for `agent/tools/*.ts` in `lint.config.ts` exists because eve names tools after their files. Keep `scripts/upload-to-drive.ts` limited to argument parsing and output, with upload logic in `scripts/lib/upload.ts` so tests can call it directly. Modules under `scripts/` and the modules they import from `agent/lib/` run under plain Node type stripping, so they import local files with explicit `.ts` extensions. Preserve the strict TypeScript and Ultracite configuration. Do not disable rules to make a port or refactor pass. Add TSDoc when introducing or changing exported helpers, tools, channels, or configuration. Document parameters with `@param name - description`, type parameters with `@typeParam`, meaningful return values with `@returns`, intentional errors with `@throws {@link ErrorType}`, and defaults with `@defaultValue`. Use `@remarks` for behavior callers need to know, such as when the Drive can be busy. Remove inline comments that repeat the code; keep those that explain a constraint the code can't express. Use `.env.example` to document new configuration without credentials. When configuration changes affect setup or behavior, update the relevant human documentation too. ## Drive behavior to preserve - Sessions mount the Drive only as a `snapshot`. A snapshot reflects the Drive when it's mounted, so saved files appear in new sessions. Never mount the Drive read-write in the session sandbox: only one sandbox can hold the read-write mount, so one session would block every save and upload. - Writes go through `withWritableDrive`, which checks `currentSessionId`, rechecks it when `Sandbox.create` fails, and throws `DriveBusyError` when another sandbox holds the read-write mount. Tools return busy as a result the model can act on, such as `drive_busy`, rather than throwing. A failed `stop()` is logged, never thrown, so it can't hide a completed write. - Resolve every model- or user-supplied path through `resolveDrivePath`, which rejects absolute paths, `.` and `..` segments, empty segments, NUL bytes, segments with leading or trailing whitespace, and segments longer than 255 bytes. - A Drive must be written to once before it can be mounted as a snapshot, and its region can't change after creation. The sandbox environment must run in `DRIVE_REGION`. `agent/sandbox.ts` falls back to an unmounted sandbox when the mount fails, and `agent/instructions.md` explains an empty or missing `/drive` to users; keep both. - Write sandboxes deny all network access, run with `persistent: false`, and stop when the callback settles. Session sandboxes deny all network access. - Keep the Saving files section of `agent/instructions.md` consistent with the `save_to_drive` description and return shapes. ## Local and hosted behavior `pnpm dev` opens eve's terminal chat. Local sessions use the same Vercel Sandbox and Drive as the deployment, so they need the Vercel OIDC token from `vercel env pull .env.local`. The token expires after 12 hours, so pull it again when the SDK reports an OIDC credentials error. Local sessions don't look up Slack profiles. The Slack channel uses `SLACK_CONNECTOR`, falling back to `slack/placeholder` so compilation works before Slack is configured. Slack delivery still needs a real connector. Pull the project's variables with `vercel env pull .env.local`. `pnpm build` also prepares a Vercel Sandbox snapshot, which needs a linked project and credentials; use `pnpm exec eve build --skip-sandbox-prewarm` to check compilation without preparing it. Use the Vercel CLI for project configuration and deployment instructions, including `vercel deploy --prod`, `vercel env add`, and `vercel sandbox`. Confirm unfamiliar flags with `--help`. Provisioning services, uploading to a Drive, or deploying the agent is separate from checking code and documentation. ## Documentation standards Keep `README.md` concise, with the deployment flow, the technology and customization tables, and short summaries that link to `CUSTOMIZATION.md` for detailed procedures. Preserve working examples and previously accepted wording when revising a section. Write for a person using the template: - Explain what a setting controls before showing it. Distinguish optional values from required configuration and state what the code does when a variable is unset. - Explain terms on first use, such as session, snapshot, and read-write mount, and use them consistently. A session is one Slack thread or one `pnpm dev` chat. - Lowercase Vercel environment names mid-sentence, such as "preview" and "production". Labels at the start of a table cell keep their capitalization. - Connect related ideas naturally. Avoid choppy sequences of short sentences, short sentences split off from the reason that explains them, forced groups of three, parenthetical asides, bold lead-ins, colons joining two sentences, and unnecessary emphasis. - Keep commands usable in context. Identify required input and explain how to recognize success. Verify behavior against code and current CLI help. When reviewing a passage, read its surrounding section for contradictions and repeated explanations. After applying an edit, check that the revision didn't introduce new problems from the list above. Formatting and link checks do not replace an editorial review. ## Validation `pnpm check` and `pnpm fix` use `lint.config.ts` explicitly to keep its Ultracite rules separate from monorepo linting. `.oxfmtrc.json` contains the resolved Ultracite formatting preset so root tooling needs no template dependencies. Keep it in sync when upgrading Ultracite. Git hooks are opt-in: run `pnpm exec lefthook install` only from a standalone checkout, never from the eve monorepo. Choose checks that establish the changed behavior. Tests live beside their implementations under `agent/` and `scripts/lib/`, and mock only the Vercel Sandbox and Slack APIs using the fixtures in `agent/lib/testing/`. | Command | Purpose | | --- | --- | | `pnpm check` | Formatting and lint rules | | `pnpm fix` | Apply formatting and lint fixes | | `pnpm typecheck` | TypeScript checks | | `pnpm exec vitest run <test-file>` | Tests for the changed behavior | | `pnpm validate` | Formatting, lint, types, all tests, and unused-code checks | | `pnpm exec eve info` | Agent diagnostics | | `pnpm build` | Production compilation | For code changes, run the relevant tests and static checks. Use `pnpm validate` for changes spanning several parts of the agent, and run `pnpm exec eve info` when changing tools, channels, the sandbox, or other framework registration. Add tests for meaningful behavior changes, especially path validation and the busy check. For documentation-only changes, check formatting and affected links or examples. Typecheck new code samples before adding them to the docs. Do not run the full application test suite for a prose edit. State which checks ran and distinguish source inspection from behavior tested against live services. - apps/templates/eve-vercel-drives-starter/CLAUDE.md (11 bytes)
@AGENTS.md
- apps/templates/eve-voice-template/AGENTS.md (288 bytes)
# eve Agent App This project uses the eve framework. Before writing code, always read the relevant guide in `node_modules/eve/docs/`. Use `eve` lowercase in user-facing copy, docs, prompts, and comments. Do not title-case it unless it is part of an exact external title or quoted text.
- apps/templates/eve-voice-template/CLAUDE.md (11 bytes)
@AGENTS.md
- apps/templates/kody-eve-template/AGENTS.md (9803 bytes)
# AGENTS.md Guidance for AI coding agents working in this repository. ## Project overview Kody, a GitHub maintainer agent built on the [eve](https://eve.dev) agent framework. A weekly schedule composes a digest email of the configured repo's open issues and sends it through the **Resend** MCP connection. Inbound email commands are intentionally disabled pending a separately authenticated authorization protocol; replies never dispatch sessions. Kody reads and triages GitHub issues through the **github** tools (GitHub Tools SDK via Vercel Connect), creates and cross-references issues through the **Linear** MCP connection, and answers when @mentioned on GitHub issues/PRs or in Linear Agent Sessions. Per-user preferences live in **Vercel Blob**. Its workflow lives in `agent/instructions.ts`. The whole agent is defined under `agent/`. eve discovers capabilities from the filesystem. See [`ARCHITECTURE.md`](./ARCHITECTURE.md) for the component map, data flow, and boundaries. ## Setup & commands ```bash pnpm install # install dependencies (Node 24.x) pnpm dev # eve dev — local TUI; run /model once to link 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 ``` Run `pnpm test` for private preference storage, channel authorization regressions, and the outbound schedule contract. **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/research.ts` is the tool `research`; an extension mounted at `agent/extensions/github.ts` prefixes its tools with `github__`; a connection at `agent/connections/linear.ts` registers as `linear`. - Authored slots: `agent/agent.ts` (model), `agent/instructions.ts` (`defineInstructions`, the system prompt; resolved at build time, injecting `RESEND_FROM_ADDRESS` into the sending-email rule), `agent/tools/*.ts` (`defineTool`, or `defineWorkflowTool` for durable workflows), `agent/extensions/*.ts` (mounted extensions), `agent/connections/*.ts`, `agent/channels/*.ts`, `agent/schedules/*.ts` (cron-triggered sessions), `agent/skills/<name>/SKILL.md`, `agent/subagents/<id>/agent.ts` (`defineAgent`), `agent/sandbox.ts`. - **Channels:** `github` (eve GitHub channel via Connect, botName "Kody"; only @mentions on `DIGEST_REPO` from a sender matching the comment author, with current write, maintain, or admin permission verified through GitHub's API; lookup failures deny dispatch), `linear` (Connect Agent Sessions with requester context), `resend` (rejects every inbound POST with HTTP 403, including previously subscribed replies), plus the `eve` route-auth channel. Automatic PR-open summaries are disabled pending an isolated read-only agent and bounded publisher. Never authorize shared Linear access from roles on unrelated repositories or historical `author_association` values. - **Tools** run in the app runtime (full `process.env`), one default export per file. Gate destructive tools with `approval` from `eve/tools/approval` (here: `clear_user_preferences`). The `github` extension (`agent/extensions/github.ts`, `@github-tools/eve-extension`) exposes the GitHub Tools `maintainer` preset as `github__<tool>` tools with credentials via Vercel Connect (the deprecated `@github-tools/sdk/connect/eve` one-liner no longer works: eve skips its tools at runtime); issue-conversation writes (`addIssueComment`, `addLabels`, `closeIssue`, `createIssue`, `removeLabel`) set `requireApproval: "never"` for authorized maintainer workflows, while higher-impact writes keep the extension's approval-by-default. The `research` tool is a `defineWorkflowTool` that opens a session with the `researcher` subagent via `ctx.agent()` and requests structured output per turn (`defineAgent` no longer takes `outputSchema`). - **Connections** are MCP servers: `linear` (`https://mcp.linear.app/mcp`, app-scoped auth shared through `linearAuth` in `agent/lib/constants.ts` with scopes `read`, `write`, `issues:create`, `comments:create`) and `resend` (`https://mcp.resend.com/mcp`, static bearer token from `RESEND_API_KEY` via `auth.getToken` — a static token works in every session including the cron run, which has no signed-in user, and the Resend connector cannot issue app-scoped tokens; list/send emails, templates, contacts). Connections accept the same `approval` field as tools if a write needs gating; neither passes one today. - **Schedules:** `agent/schedules/weekly-digest.ts` runs cron `0 9 * * 1` (Mondays 09:00 UTC) in markdown task mode: the prompt tells the agent to fetch open issues on `DIGEST_REPO` with the GitHub tools and send the digest to `DIGEST_EMAIL` itself with the Resend MCP tools, which gives it control of the subject line (the chat-sdk Resend adapter cannot set a subject on outbound-initiated threads). `DIGEST_REPO`, `DIGEST_EMAIL`, and `RESEND_FROM_ADDRESS` are required at module load via `requireEnv`, so a missing value fails discovery instead of producing a schedule that cannot send. The digest's structure lives in the `digest-format` skill; the schedule prompt carries only the run-specific facts (repo, recipient, sender, subject). Replies are not processed. Never invite email replies; direct follow-up to tracker links or authorized GitHub mentions. - **Skills** are load-on-demand. A packaged skill (`<name>/SKILL.md`) requires `description` frontmatter; that description is the routing hint. The skills here are `writing-quality`, `digest-format`, `triaging-issues`, and `github-linear-bridging`. - **Subagents** are declared under `agent/subagents/<id>/agent.ts` (`defineAgent`, required `description` — the routing hint). The directory name is the identity and the lowered tool name (no namespace; it must not collide with a tool name, and eve's build still rejects the collision even when the subagent sets `tool: false`, so a wrapping tool needs its own name, like `research`). 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`. The one subagent here is `researcher`; it sets `tool: false` and is reached only through the `research` workflow tool. - After editing, **check LSP diagnostics / `pnpm typecheck`** and fix type errors before moving on. ## Code style - Linting and formatting are handled by **Ultracite** (a Biome preset). Run `pnpm check` before finishing and `pnpm fix` to auto-fix. Config is in `biome.jsonc`; the kebab-case filename rule is disabled there because eve tools use snake_case names. - TypeScript strict; ESM with `NodeNext` resolution (relative imports need a `.js` extension). Prefer `const`, arrow functions, optional chaining / nullish coalescing. - Validate tool input/output with `zod` schemas. - Document exported config with **TSDoc** (`@remarks`, `@param`, `@returns`, `@defaultValue`, `@see`). Avoid inline `//` comments — put rationale in the TSDoc block instead. - Prose in markdown files is not hard-wrapped: write each paragraph or bullet as one line. - Agent-facing text (instructions, skill bodies, tool and subagent descriptions) follows the "How you write" rules in `agent/instructions.ts`: no em dashes, no machine-made words, no bold for emphasis. It carries behavior only, never framework plumbing (sign-in flows, how approvals render) or references to tools and skills the reading agent can't access. ## Security - **Never ask the user for API keys, client secrets, or any other credentials.** - **Never commit secrets.** `.env*` is gitignored. Connector UIDs are read from env (`GITHUB_CONNECTOR`, `LINEAR_CONNECTOR`); GitHub and Linear auth is brokered by Vercel Connect (Linear is app-scoped through `linearAuth`; tokens are resolved per call and never exposed to the model) and Blob auth is via the project's OIDC token. The outbound Resend MCP connection authenticates with `RESEND_API_KEY`, read from env and never committed. Inbound email is disabled in code; no webhook secret or Redis state is required. Other config comes from env too: `DIGEST_REPO`, `DIGEST_EMAIL`, `RESEND_FROM_ADDRESS` and optional `RESEND_FROM_NAME` (the sender identity, resolved at build time; the name falls back to "Kody"), legacy `REDIS_URL` and `RESEND_WEBHOOK_SECRET` values are unused. Re-enabling email commands requires separately authenticated, installation-bound authorization, not a From allowlist, thread header, or webhook signature. - If you ever build a `RegExp` from data, escape it (literal match) and bound the input length. - Gate irreversible or high-impact actions behind `approval` (here: `clear_user_preferences`). - For per-user storage, derive the key from the resolved principal (`ctx.session.auth.current`), never from model input — see `agent/lib/user-preferences.ts`. The preference files live in a private Blob store under the reserved `user-preferences/` prefix, reachable only through the principal-scoped preference tools. ## Before committing - `pnpm validate` passes (Ultracite check, `tsc`, and `eve info` with 0 errors / 0 warnings). - No secrets, `node_modules`, or build output (`.eve`, `.vercel`, `.output`) staged.
- apps/templates/kody-eve-template/CLAUDE.md (11 bytes)
@AGENTS.md
- apps/templates/marketing-team-eve-template/AGENTS.md (33681 bytes)
# AGENTS.md Guidance for AI coding agents working in this repository. ## Project overview This repository holds a team of marketing agents built on the [eve](https://eve.dev) agent framework. The root **lead** agent holds the shared product picture (brand context in Vercel Blob) and routes each request to one specialist: `product-marketer` for positioning and messaging, `content-marketer` for long-form pieces, `social-media-coordinator` for short-form posts and the Typefully queue, `seo` for organic search work, or `email` for adapting copy into mail and running Resend. The five specialists have no subagents of their own: each does its own web research and its own review pass inline. The lead's workflow lives in `agent/instructions.md`; each specialist's lives in `agent/subagents/<id>/instructions.md`. The lead picks a specialist by reading `description` in each `agent.ts`, so adding a specialist means adding a directory. Nothing in `agent/instructions.md` enumerates them, and nothing should. The whole agent is defined under `agent/`. eve discovers capabilities from the filesystem. See [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) for the component map, data flow, and boundaries. ## Setup & commands ```bash pnpm install # install dependencies (Node 24.x) pnpm dev # eve dev, the local TUI; /login connects a model provider, /model switches models 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 + offline evals in one command pnpm eval:offline # evals/offline on mock models: no model calls, runs in seconds pnpm eval # evals/live on real models (needs AI Gateway credentials) ``` **Verify changes with `pnpm validate` (lint, typecheck, and discovery diagnostics must all report 0 errors / 0 warnings, and the offline evals must pass), run `pnpm eval` when you have credentials, then exercise the agent in the `pnpm dev` TUI.** The evals come in two suites. `evals/offline/` runs every agent on the scripted mock in `lib/mock-model/config.ts`, so it exercises tools, approvals, memory, and delegation with no model call, and it tests the pure helpers directly: the Slack identity rules, the reserved Blob prefixes, artifact ids, the banned-words match, and the pre-send patterns. `evals/live/` is three narrow cases on real models. Two of them assert `judged: true` for the decision-model tools, because `judgeRules` fails open and a blocked or broken decision model is otherwise invisible. They need an AI Gateway team whose provider allow list permits the decision model's provider. `npx eve info` is the fastest way to confirm a change landed: it prints every discovered tool, skill, connection, and subagent. When a file you added doesn't show up there, discovery didn't classify it as an authored slot, and `.eve/discovery/diagnostics.json` says why. ## eve conventions - **Read the relevant guide in the installed eve package's `docs/` before writing code.** Don't invent framework APIs; confirm them against the docs. Under pnpm the real path is `node_modules/.pnpm/eve@<version>_<hash>/node_modules/eve/docs/`, so resolve it with `ls -d node_modules/.pnpm/eve@*/node_modules/eve | head -1`, because plain `node_modules/eve/docs/` globs don't resolve. - **Identity comes from the filesystem, never a `name` field.** The tool at `agent/tools/save_brand_context.ts` is the tool `save_brand_context`; the subagent at `agent/subagents/content-marketer/` is the tool `content-marketer`. - Authored slots: `agent/agent.ts` (model), `agent/instructions.md` (system prompt), `agent/tools/*.ts` (`defineTool`), `agent/connections/*.ts`, `agent/channels/*.ts`, `agent/memory/*.ts` (`defineMemory`, root only here), `agent/skills/<name>/SKILL.md`, `agent/subagents/<id>/agent.ts` (`defineAgent`), `agent/sandbox.ts` (the lead declares none; each specialist has its own). `agent/lib/` holds plain modules, not a slot. The same slots nest: every subagent directory can carry its own `instructions.md`, `tools/`, `connections/`, `skills/`, `sandbox.ts`, and `subagents/`. - **Subagents inherit nothing.** Every declared subagent runs in a fresh child session with none of the parent's skills, connections, tools, or sandbox, so the caller packs everything into the `message`. This is why all five specialists have their own `get_brand_context` tool, their own `sandbox.ts`, and their own `connections/notion.ts`. The Notion connection itself is defined once, as `notionConnection()` in `lib/notion/connection.ts`, and each of the six files is a one-line call, so the approval list is edited in one place. - **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: the shared Notion connection in `lib/notion/connection.ts` substring-matches an `APPROVAL_REQUIRED_TOOLS` list, and `typefully.ts` goes further, gating deletes, all `edit_draft` calls, and queue-schedule changes unconditionally but letting `create_draft` through when the call is recognizably a plain draft with no publish time. Edits are partial updates, so omitting a publish time can retain an existing schedule. `resend.ts` and `typefully.ts` also narrow which tools the model can discover at all, with `tools.allow`; see [The email agent's two boundaries](#the-email-agents-two-boundaries). - **Skills** are load-on-demand. Every packaged skill (`<name>/SKILL.md`) requires `description` frontmatter; that description is the routing hint and the only thing the model sees before loading. The `references/` files under a skill require a sandbox to materialize, so an agent with reference files needs its own `sandbox.ts`. The frontmatter is YAML, so an unquoted `description` containing a colon followed by a space fails to parse and the skill is dropped with a `discover/skill-frontmatter-invalid` error. Rephrase around the colon rather than quoting, to match the rest of the descriptions. - **`agent/lib/` is the only real reuse mechanism.** eve has no shared-skill mechanism, and extensions are root-only, so everything two agents both need lives in `lib/<domain>/` as a factory: Blob paths, the asset tools, the style lint, and the `writing-quality` skill. Shared _procedures_ are either duplicated markdown or a `defineSkill` factory, per [Shared skills](#shared-skills). - **Every agent sets `defaultTools: false`** and adds back only the built-ins it uses, so a built-in that a later eve release adds stays off until someone opts in. The lead adds none: it has no shell, no sandbox file tools, no web tools, and no root-copy `agent` tool, and works through its authored tools, `workflow`, and the specialists. Each specialist adds `read_file` (how it opens its skills' `references/` files), `web_fetch`, and `web_search`, as one small file each under `tools/`. Nothing writes to a sandbox, so `write_file`, `edit_file`, and `bash` stay off everywhere. With no shell, web reading goes through `web_fetch`, which returns one converted document per source instead of raw markup pulled with `curl`. - **`ask_question` is on the specialists and not on the lead.** A specialist's reply goes to the lead, so plain text can't reach the person mid-task and the tool is the only way to ask them. The lead talks to the person directly and asks in its reply. - After editing, **check LSP diagnostics / `pnpm typecheck`** and fix type errors before moving on. ## Shared code layout `agent/lib/` is organized by domain: a `config.ts` (constants, key layout, pure helpers) and a `tools.ts` (tool factories), and nothing else. Two domains carry a different second file, named for what they share: `lib/writing-quality/skill.ts` shares a skill, and `lib/notion/connection.ts` shares a connection. Two files per domain is the rule, and the way it breaks is a directory quietly becoming a home for whatever didn't have one. When you reach for a third file, that's the signal you have a second domain: split it and name it for what it holds. `lib/artifacts/` and `lib/tracking/` were both once extra files inside `lib/content/`. | Directory | Holds | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `lib/vercel-blob/` | Blob path layout, reserved-prefix guards, and the five asset tool factories | | `lib/brand-context/` | the brand context Blob key, its size cap, and its two tool factories | | `lib/models/` | every model id, one constant per role. Config only | | `lib/mock-model/` | the `EVE_MOCK_MODEL` switch and the scripted mock every agent runs on in the offline evals. Config only | | `lib/slack/` | the Slack connector credentials and the pure rules that turn a message into a session identity. Config only | | `lib/notion/` | the shared Notion connection as `notionConnection()`. It carries a `connection.ts` because what it shares is a connection | | `lib/content/` | the pure banned-words matching and the style judgment rules, behind `lintAgainstStyleTool(listsBySurface)` | | `lib/decisions/` | the uncertain band and `judgeRules()`, the one place a decision model is called. Config only, consumed by the two tools that ask a decision model | | `lib/email/` | the pre-send copy patterns and rules, behind `checkSendReadinessTool()` | | `lib/artifacts/` | the handoff-artifact key layout, id format, and bounds, behind `saveArtifactTool()` and `readArtifactTool()` | | `lib/tracking/` | the campaign-tag vocabulary and URL building, behind `buildTrackedLinkTool(surfaces)` | | `lib/writing-quality/` | the surface-independent prose rules as one shared skill. `config.ts` holds the markdown; `skill.ts` assembles it with `writingQualitySkill()`. See [Shared skills](#shared-skills) | **Tool and skill files export a factory call, not a re-export.** Two lint rules box this in: `noBarrelFile` rejects `export { x as default } from "..."`, and `noExportedImports` rejects `import { x } from "..."; export default x;`. The only shape that passes both is a factory in `lib/` plus a call in the authored file: ```ts // agent/subagents/content-marketer/tools/lint_against_style.ts import blog from "../skills/blog-style/references/banned-words.json" with { type: "json" }; import { lintAgainstStyleTool } from "#lib/content/tools.js"; export default lintAgainstStyleTool({ blog }); ``` The lint tool imports each surface's `banned-words.json` straight from the style skill, because tool code has no handle on a skill's files at runtime. The skill stays the only copy of the list: the model reads it in the sandbox and the tool reads it from the bundle. Adding a surface means adding its import here, next to its `<surface>-style` skill. `validate_schema` reads the `schema` skill's `required-properties.json` the same way. The built-in tools a specialist adds back (`ask_question`, `read_file`, `web_fetch`) have nothing to call: eve exports each as a ready definition, so the file binds it to a local `const` and exports that, which is the shape `noExportedImports` accepts. Each is identical across the five specialists, so edit the copies together. Imports use the `#*` subpath from `package.json` (`#lib/...` maps to `agent/lib/...`) and **always carry a `.js` extension**, even though the source is `.ts`. ## Shared skills Skills are scoped to the agent that declares them and eve has no shared-skill mechanism, so its docs tell you to copy the markdown under each `skills/` directory. `writing-quality` doesn't: every specialist that touches prose needs it, and keeping byte-identical directories in step by hand is work nobody remembers to do. Instead it's a `defineSkill` factory in `lib/`, called from a one-line file per agent, which is exactly the shape the tool factories use: ```ts // agent/subagents/content-marketer/skills/writing-quality.ts import { writingQualitySkill } from "#lib/writing-quality/skill.js"; export default writingQualitySkill(); ``` Four things to know before you touch it: - **The prose lives in `lib/writing-quality/config.ts`** as template literals, because `description` and `content` are typed as `string` and eve refuses `.md` files under `lib/`. Edit that file as a document, not as code, and keep any backtick inside a literal escaped. - **`files` entries materialize as real siblings**, so `references/ai-phrases-to-avoid.md` still resolves from the markdown body. The compiled package is byte-identical to the directory it replaced, minus the frontmatter block: the description now travels in the manifest instead of the file. - **The skill name comes from the calling file's slug**, so every caller has to sit at `skills/writing-quality.ts`. Rename the file and the skill renames with it, silently breaking the `instructions.md` files that ask for it by name. - **Skill names must start with an alphanumeric character.** One that doesn't is dropped from discovery with no diagnostic and no entry in the manifest, which is a genuinely confusing five minutes. Specialization still belongs in the per-surface style skills (`blog-style`, `x-style`, and so on) and in each agent's `instructions.md`, never in a fork of the shared rules. No skill is duplicated today: `content-editing` belongs to the content marketer alone, and everything else is either per-surface or shared from `lib/`. If you ever add a second copy of a procedure, copy the markdown as eve's docs describe and - apps/templates/marketing-team-eve-template/CLAUDE.md (11 bytes)
@AGENTS.md
- apps/templates/openinstinct/AGENTS.md (7197 bytes)
# eve Agent App This project uses the eve framework: an agent is a directory of files under `agent/`, and eve compiles and runs it. For a content-only change to the root agent's identity, purpose, tone, or response guidelines, edit its existing authored instructions. Fresh projects use `agent/instructions.md`; a project may instead use `agent/instructions.ts` or files under `agent/instructions/`. You do not need to read the framework docs for a content-only instructions change. A fresh project already has its selected model in `agent/agent.ts`; preserve that file unless the user asks to change the model. ## Read the docs before writing code ```sh ls node_modules/eve/docs ``` Start with `docs/README.md`: it maps each task to the page that covers it. Read that page before authoring tools, connections, channels, skills, subagents, schedules, or deployment. In a workspace or local package install, resolve the installed `eve` package location first. If the package docs are missing, use https://eve.dev/docs. Use a bounded authoring loop: 1. Read the relevant page and inspect only files you will modify or need to imitate. 2. Stop discovery once the file location, imports, and definition shape are clear. Implement the smallest complete behavior the user requested. 3. Run one narrow verification. Expand investigation only when it fails or the request needs project-specific details. Follow links or inspect public types only when the routed page leaves the task unanswered. Do not recursively glob `node_modules`, enumerate the entire docs tree, or read unrelated scaffold files when the direct path is known. Package-manager links can hide files from recursive glob tools even though direct reads work. ## Prefer an existing integration When a task names an external product or service, search the registry before implementing its integration. For a generic capability, author a tool instead. ```sh eve registry search <query> --json eve registry view <item> ``` Prefer items whose `implementation` is `native`; use Chat SDK adapters when no native channel fits. `registry view` links the item's documentation. Install without driving interactive prompts: ```sh eve add <item> --non-interactive ``` Exit code 0 means setup completed, 1 failed, and 2 needs an answer or a prerequisite. On exit 2, run the `next.command` from the final NDJSON event. For a non-secret question, replace its `<JSON value>` answer placeholder with the answer you collected; string values need JSON quotes. Never pass a secret in `--answer`. See `docs/install-integrations.mdx` for setup prerequisites. ## Use eve for Vercel operations Use eve to link and deploy Vercel projects: ```sh eve link --non-interactive --project <name-or-id> [--team <team-id-or-slug>] eve deploy --non-interactive --yes [--project <name-or-id>] ``` A setup may report `eve link` as a prerequisite; run it, then retry the continuation. When a completed setup event has `deploymentRequired: true`, run the `next` command it reports. ## Validate the change Run the validation the task requests. When it does not establish the behavior you changed, run the narrowest relevant check. ## Repository contract - The repository root owns the single Next.js application, Eve agent, and shared UI contract. - The workspace manager lives on `/` and the agent chat on `/chat`; browser execution belongs only to the declared browser-agent subagent's flat tool surface under `agent/subagents/browser-agent/tools`. - Keep each worker browser tool's schema and implementation together. Share the Kernel SDK client through `agent/subagents/browser-agent/lib/kernel.ts`; do not add a Kernel extension or root browser connection. - `agent/subagents/browser-agent/lib` is for code genuinely shared by worker tools. Group a shared worker domain in a lower-case folder, such as `trace/domains.ts` or `autofill/provider.ts`; do not use it as a holding area for a tool's one-off logic. - Validate runtime environment variables through `shared/environment/env.ts`. `KERNEL_API_KEY` is required by the worker browser tools. - Run `pnpm check` and `pnpm build` before handing off changes. ## Code organization - Treat `shared` as a narrow contract boundary, not a default destination for application code. A file belongs there only when at least two of `agent`, `app`, `web`, and `db` consume it; put database access in `db/services`, agent behavior under `agent`, and route or section behavior with its route. - Do not add a generic `modules` layer. Give code a concrete owner and colocate it there. A route section owns its section components, forms, and local parsing; split it only when the files have distinct responsibilities. - Prefer one cohesive call-site file for code used once. Do not add production factories, dependency containers, server wrappers, or files solely to make a unit test easier to mock. - Mock imported modules at their owning or external boundary in tests. Do not export mutable dependency bags, dependency setters, reset hooks, or other test-only seams from production modules; keep production exports limited to application behavior and real domain contracts. - Use lower-case file and folder names. When several files share a domain prefix, make that prefix a folder and name files for their role, such as `trace/domains.ts` rather than `trace-domains.ts`. Do not introduce camel-case filenames. - Avoid catch-all names such as `manager`, `store`, `helpers`, or `utils` for feature ownership. Reuse an existing narrowly named boundary or place the code at the concrete owner instead. ## Design system Before planning or changing product UI: - Build from the primitives in `web/components/ui` and the semantic `type-*` typography utilities defined in `app/styles/brand/typography.css`. - Preserve the current `components.json` primitive base and local extensions; add new primitives with the official shadcn CLI. ## Type ownership - Keep each TypeScript concept anchored to one source of truth. - Before adding a `type` or `interface`, search for an existing owning export, schema-derived type, model inference, or function/value type that can be reused or derived. - Prefer inference for implementation details and contextual callbacks. - Add a named type only for a real domain concept, public boundary, validation source, or meaningfully reused composition. - Do not mirror schemas, database rows, router inputs or outputs, SDK payloads, library exports, or function results with parallel interfaces. <!-- BEGIN:nextjs-agent-rules --> # This is NOT the Next.js you know This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices. This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean. <!-- END:nextjs-agent-rules -->
- apps/templates/openinstinct/CLAUDE.md (11 bytes)
@AGENTS.md
- apps/templates/personal-agent-template/AGENTS.md (2726 bytes)
# Personal Agent Template Durable personal AI assistant built with eve and Nuxt. ## Quick Reference | Command | Description | | ---------------------- | ----------------------------------------- | | `pnpm install` | Install dependencies | | `pnpm dev` | Start the Nuxt web app | | `pnpm dev:all` | Start the local Vercel service graph | | `pnpm build` | Production build | | `pnpm test:smoke` | Sign up against the production build | | `pnpm test:regression` | Focused chat recovery and rendering tests | | `pnpm typecheck` | TypeScript check | | `pnpm db:generate` | Generate Drizzle migrations | | `pnpm db:migrate` | Apply migrations | ## Structure ``` personal-agent-template/ ├── agent/ # eve agent (channels, tools, skills, connections) ├── apps/web/ # Nuxt UI, Nitro API, and shared application code └── docs/ # Architecture, environment, customization ``` ## Documentation - [Architecture](docs/ARCHITECTURE.md) — System design, request flows, internal API - [Environment](docs/ENVIRONMENT.md) — Environment variables - [Customization](docs/CUSTOMIZATION.md) — Rename agent, add tools, integrations - [README](README.md) — Quick start and feature overview ## eve framework This project deploys its Nuxt frontend and eve agent as peer Vercel services through `vercel.ts`. Before writing agent code, read the relevant guide in `node_modules/eve/docs/`. ## Internal API Pattern The eve agent calls Nuxt over HTTP: ``` agent/lib/*-internal.ts → /api/internal/* → server/utils/* ``` Authenticated with `Authorization: Bearer <INTERNAL_API_SECRET>`. See [`apps/web/server/utils/internal-api.ts`](apps/web/server/utils/internal-api.ts). ## Memory Flow 1. **Session injection** — [`agent/instructions.ts`](agent/instructions.ts), with the profile memoized per user 2. **Agent save** — [`agent/tools/save_memory.ts`](agent/tools/save_memory.ts) with web approval UI 3. **Profile UI** — import, view, edit, delete on Settings → Profile Categories: [`lib/types/memory.ts`](lib/types/memory.ts). One prose block per category; saves replace the full block. ## Customization Checklist - [`lib/agent.ts`](lib/agent.ts) — branding - [`agent/lib/base-instructions.ts`](agent/lib/base-instructions.ts) — persona - [`agent/channels/slack.ts`](agent/channels/slack.ts) — Slack Connect slug - [`agent/agent.ts`](agent/agent.ts) — AI model See [docs/CUSTOMIZATION.md](docs/CUSTOMIZATION.md) for details.
- apps/templates/personal-agent-template/CLAUDE.md (11 bytes)
@AGENTS.md
- apps/templates/sanity-copilot-eve-template/AGENTS.md (13644 bytes)
# AGENTS.md Guidance for AI coding agents working in this repository. ## Project overview A Slack-based Sanity copilot built on the [eve](https://eve.dev) 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), stores files in a private Vercel Blob store, and remembers each user's standing preferences in eve memory. Its workflow lives in `agent/instructions.md`. The whole agent is defined under `agent/`. eve discovers capabilities from the filesystem. Offline and live evals live under `evals/`. See [`ARCHITECTURE.md`](./ARCHITECTURE.md) for the component map, data flow, and boundaries. ## Setup & commands ```bash 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 eval:offline # six offline evals on mock models (EVE_MOCK_MODEL=1 eve eval offline) pnpm eval # three live evals on real models (eve eval live); costs money, not part of validate pnpm sync:shared # copy shared-references/ into both writing-quality skills (also runs before dev and build) pnpm validate # shared-reference check + check + typecheck + eve info + eval:offline in one command ``` `pnpm test:smoke` runs focused asset path, URL, download limit, and pagination regressions without network calls or credentials. The broader checks are six offline evals under `evals/offline/` that run the real tools, approvals, memory, and subagent delegation on mock models, so they need no model provider. `EVE_MOCK_MODEL=1` swaps every agent's model for a mock from `agent/lib/mock-model.ts`; never set it on a deployment. Verify changes with `pnpm validate` (the shared-reference copies must be up to date, lint, typecheck, and discovery diagnostics must all report 0 errors / 0 warnings, and every offline eval must pass), then exercise the agent in the `pnpm dev` TUI. Three live evals under `evals/live/` (`research/quick`, `review/revise`, `quality/short-draft`) run with `pnpm eval`. They call real models through the AI Gateway, so every run costs money and they are not part of `pnpm validate`. They need Gateway credentials for a team that allows the `google` provider (the decision model is `google/gemini-decision-1`) and has a credit balance. ## 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/memory/*.ts` (`defineMemory`), `agent/sandbox.ts`. Evals are authored outside `agent/`: `evals/evals.config.ts` (`defineEvalConfig`) and `evals/**/*.eval.ts` (`defineEval`). Shared helpers that are not slots live in `agent/lib/`. This repo also has `agent/subagents/<id>/skills/`, `agent/subagents/<id>/tools/`, 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`. A file that exports `disableTool()` from `eve/tools` removes the built-in tool of the same name: `agent/tools/bash.ts`, `write_file.ts`, and `edit_file.ts` do that for the root. 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 `notion-update-pages`, `notion-move-pages`, `notion-update-data-source`, and `notion-update-view` (creation is ungated). - **Sanity Context** is an optional connection at `agent/connections/sanity-context.ts` (connection filenames allow lowercase letters, digits, and dashes only, so no underscore). It is a `defineDynamic` from `eve/connections` that returns `null` unless both `SANITY_CONTEXT_MCP_URL` and `SANITY_ORGANIZATION_TOKEN` are set, so a default deployment has no such connection. It is read-only and ungated, and it authenticates with an organization API token shared by every user. `instanceKey` is required on a dynamic connection with auth. Don't mention it in `agent/instructions.md`: the model learns about it from the connection's `description`, which exists only when the connection does. - **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`. - **Memory** is declared under `agent/memory/<name>.ts` (`defineMemory`). `agent/memory/preferences.ts` uses `fileMemory()` scoped with `byPrincipal`, and only for a `principalType: "user"` session. eve recalls the user's document into the conversation each turn and generates the `preferences__save_memory` and `preferences__remove_memory` tools, so there are no hand-written preference tools. Storage is in-process under `eve dev`. On Vercel it is the project's private Blob store, the same one the asset tools use, under the `eve/memory/` prefix. It needs no setup command: per `node_modules/eve/docs/memory/file.md`, `fileMemory()` falls back to the project's attached store (`BLOB_STORE_ID`, with OIDC) when `EVE_MEMORY_BLOB_STORE_ID` is unset. - **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`). Both subagents here set `tool: false`, and the root reaches them through the `defineWorkflowTool` wrappers `agent/tools/research.ts` and `agent/tools/review_draft.ts`. Each wrapper's `execute` body is marked `"use workflow"` and calls `askSubagent` (`agent/lib/subagent.ts`), which runs `ctx.agent(<id>).send(message, { outputSchema })` once and returns the validated structured result. Every call is a one-shot fresh child session that ends when the call finishes; nothing carries over between calls. Keep each subagent's `description` in step with its wrapper tool's. A declared subagent 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` (`webSearch({ provider: "parallel" })`) and `web_fetch` under its own `tools/`, so it has no sandbox tools. Its model is routed per call with `auto()` from `eve/models`: a decision model reads the research message and picks the deep or the standard research model, and the `research` tool's optional `depth` input (`quick`, `standard`, `deep`) is prefixed to the message as a routing hint. `research` rejects a `message` over 15,000 characters. The reviewer sets `defaultTools: false` and re-adds only `read_file` (`agent/subagents/reviewer/tools/read_file.ts`), which it needs to read its skill's reference files, so it has no shell, file-write, or web tools. It carries its own copy of the `writing-quality` skill under `agent/subagents/reviewer/skills/` plus its own `sandbox.ts`. The two reference files both copies share word for word (`ai-phrases-to-avoid.md`, `plain-english-alternatives.md`) have a single source in `shared-references/`; `scripts/sync-shared.mjs` copies them into both skills' `references/` folders on `predev` and `prebuild` and as `pnpm sync:shared`. Edit the shared files, never the copies. The other three files (`SKILL.md`, `web-content-specs.md`, `web-writing-best-practices.md`) are hand-maintained in each copy and intentionally diverge where the root's references other root-only skills (`seo-aeo-best-practices`); when editing either copy of those, keep them in step except for that. - **Models** are all named in `agent/lib/models.ts` (`ROOT_MODEL`, `REVIEW_MODEL`, `DEEP_RESEARCH_MODEL`, `STANDARD_RESEARCH_MODEL`, `DECISION_MODEL`). Change a model there, not in an `agent.ts`. - After editing, **check LSP diagnostics / `pnpm typecheck`** and fix type errors before moving on. ## Code style - Linting and formatting are handled by **Ultracite** (a Biome preset). Run `pnpm check` before finishing and `pnpm fix` to auto-fix. Config is in `biome.jsonc`; the kebab-case filename rule is disabled there because eve tools use snake_case names. - TypeScript strict; ESM with `module: esnext` and `moduleResolution: bundler` (see `tsconfig.json`). The resolver does not require it, but relative imports in this repo are written with a `.js` extension; keep that. `package.json` also maps `#*` to `./agent/*` and `#evals/*` to `./evals/*` (for example `#lib/reserved-paths.js`). Prefer `const`, arrow functions, optional chaining / nullish coalescing. - Validate tool input/output with `zod` schemas. - Every dependency in `package.json` is pinned to an exact version. Keep it that way when adding or upgrading one, and bump `@biomejs/biome` and `ultracite` together. - Document exported config with TSDoc (`@remarks`, `@param`, `@returns`, `@defaultValue`, `@see`). Avoid inline `//` comments; put rationale in the TSDoc block instead. - Prose in markdown files is not hard-wrapped: write each paragraph or bullet as one line. - Agent-facing text (instructions, skill bodies, tool and subagent descriptions) follows the "How you write" rules in `agent/instructions.md`: no em dashes, no machine-made words, no bold for emphasis. The skills vendored from Sanity's Agent Toolkit (every skill under `agent/skills/` except `writing-quality`) are exempt, so they stay easy to update from upstream. It carries behavior only, never framework plumbing (sign-in flows, how approvals render) or references to tools and skills the reading agent can't access. ## Security - **Never ask the user for API keys, client secrets, or any other credentials.** - **Never commit secrets.** `.env*` is gitignored. Connector UIDs are read from env (`SLACK_CONNECTOR`, `SANITY_CONNECTOR`, `NOTION_CONNECTOR`); Sanity and Notion auth is per-user via Vercel Connect and Blob auth is via the project's OIDC token, so there are no API keys in code. The one static credential is `SANITY_ORGANIZATION_TOKEN`, used only when the optional Sanity Context connection is enabled; it is read from env and never written in code. - If you ever build a `RegExp` from data, escape it (literal match) and bound the input length. - Gate irreversible or high-impact actions behind `approval`: the destructive tool `delete_asset` and connection writes (the `sanity` and `notion` connections gate the write tools listed above). - For per-user storage, derive the scope from the resolved principal (`ctx.session.auth.current`), never from model input. See `agent/memory/preferences.ts`, which scopes memory with `byPrincipal` and returns `null` for any session that is not a signed-in user. - The Blob store is private. `upload_asset` always writes with `access: "private"` and has no `access` input, `download_asset` reads through `get(url, { access: "private" })` from `@vercel/blob`, and no asset tool returns a download link. An asset's URL is an identifier for the other asset tools, not a link a person can open. - The asset tools refuse two reserved Blob prefixes (`agent/lib/reserved-paths.ts`): `eve/memory/`, where file memory keeps its documents in the same store, and `user-preferences/`, where an older store may still hold per-user preference files. That stops them being used to read or overwrite another user's preferences. - `delete_asset`, `get_asset_info`, and `download_asset` share `checkBlobUrl` in `agent/lib/blob-url.ts`: HTTPS on `*.blob.vercel-storage.com`, no credentials or custom port, and only the checked, serialized URL reaches the SDK. Reserved prefix roots and ambiguous paths fail closed, including repeated separators; never normalize unsafe storage input into an allowed path. - Keep built-in tools to what each agent uses. Root: `read_file` (skills read their reference files with it), `web_fetch`, `web_search`, and `agent`, with `bash`, `write_file`, and `edit_file` disabled. Researcher: `web_search` and `web_fetch` only. Reviewer: `read_file` only. ## Before committing - `pnpm validate` passes (shared-reference check, Ultracite check, `tsc`, `eve info` with 0 errors / 0 warnings, and the offline evals). - No secrets, `node_modules`, or build output (`.eve`, `.vercel`, `.output`) staged. - apps/templates/sanity-copilot-eve-template/CLAUDE.md (11 bytes)
@AGENTS.md
- apps/templates/slack-company-brain-template/AGENTS.md (4029 bytes)
# Slack company brain This project is an eve agent that people reach in Slack. Before writing code, read the relevant guide in `node_modules/eve/dist/docs/public/`. ## Layout - `agent/instructions.md`: the root prompt. Keep it about behavior that applies to every turn: grounding, citations, source routing and handoffs, response length, and Slack style. - `agent/instructions/{github,notion,linear,pagerduty}.ts`: until the matching `<service>/company-brain` connector is attached, tell the agent that source isn't connected and give the `vercel connect create` command. Delete each once its source works. - `agent/connections/{notion,linear,pagerduty}.ts`: turn on once their connectors are attached. Detection and setup notes live in `agent/lib/connect.ts`. - `agent/channels/slack.ts`: who can reach the agent and what context each message carries. - `agent/channels/eve.ts`: eve's HTTP API. Grants tool stubs only to `localDev()` callers, for `evals/`; production keeps eve's default auth. - `evals/`: `eve eval` checks for the reply rules in `instructions.md`, run on the real model with Slack tools stubbed. `evals/lib/slack.ts` builds messages in the Slack channel's model format, since evals run over HTTP. Keep its guidance text in sync with `FOLLOWED_THREAD_GUIDANCE` in `agent/channels/slack.ts`, and its scheduled-run message in sync with `run` in `agent/schedules/tasks.ts`. - `agent/schedules/tasks.ts`: schedules people create by asking in Slack (experimental `defineDynamicSchedules`). The destination and creator come from the Slack session in `preparePayload`, never from the model. - `agent/extensions/code.ts` and `agent/extensions/git.ts`: eve's code and git extensions, for running code in the Vercel Sandbox (`agent/sandbox.ts`) and, with the `github/company-brain` connector, GitHub access through `git__gh`. The `authorize` callback in `git.ts` is the only access check on GitHub commands. - `agent/extensions/skills.ts`: eve's experimental custom skills extension. People save their own versioned skills by asking: personal ones follow them everywhere, and channel ones apply to everyone in a Slack channel once their author approves them. Stored in memory's Blob store; scopes come from the trusted session, never from model input. - `agent/memory/`: two file memory slots. `personal` is per person and only on in private conversations; `channel` is per Slack channel. Scopes come from `agent/lib/conversation.ts`, never from model input. - `agent/tools/search_slack.ts`: Slack's Real-time Search API, public channels only. It reads the `action_token` auth attribute that eve's `defaultSlackAuth` sets in `agent/channels/slack.ts`. `agent/tools/read_slack_conversation.ts` reads a public channel or thread the bot is in. `agent/tools/post_slack_file.ts` uploads a sandbox file to the session's own Slack thread, taken from channel metadata, never model input. All three use `callSlack` from `agent/lib/slack.ts`. - `agent/skills/`: procedures and reference material loaded on demand. - `agent/connections/`, `agent/tools/`, `agent/subagents/`, `agent/extensions/`: added as the brain grows. Names come from file paths. ## Extending - Add a knowledge source as a connection (see `agent/connections/notion.ts`, or `eve add connection/<name>`) or a tool, not by pasting its content into instructions. - Give a group of related sources its own subagent when it needs its own prompt, tools, or model. Write the subagent's `description` as a routing contract: what it owns, example questions, what to pass it, what it returns, and what it is not for. The root agent routes from that text alone. - Put company facts in `agent/skills/company-context/`, not in `instructions.md`. - When you change reply behavior in `instructions.md`, add or update an eval under `evals/` and run it with `pnpm eval <dir> --repeat 3`. - Keep access checks in `agent/channels/slack.ts` and inside any tool that reads or writes sensitive data. - apps/templates/slack-company-brain-template/CLAUDE.md (11 bytes)
@AGENTS.md
- CLAUDE.md (11 bytes)
@AGENTS.md
- docs/guides/remote-agents.md (20561 bytes)
--- title: "Remote Agents" description: "Call another eve deployment as a subagent with defineRemoteAgent: the same tool call as a local subagent, with outbound auth and durable callbacks." --- A remote agent is a separately deployed eve agent that your agent calls as a subagent. Define one with `defineRemoteAgent` in a file under `agent/subagents/`. The tool name comes from the file path, so `agent/subagents/weather.ts` is the `weather` tool. ```ts title="agent/subagents/weather.ts" import { defineRemoteAgent } from "eve"; import { vercelOidc } from "eve/agents/auth"; export default defineRemoteAgent({ url: "https://weather-agent.example.com", description: "Answers weather, temperature, forecast, wind, rain, and snow questions.", auth: vercelOidc(), }); ``` `defineRemoteAgent` accepts: | Parameter | Type | Required | Default | Description | | ------------------ | --------------------------------------------- | -------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | `string \| (() => string \| Promise<string>)` | Yes | n/a | Base URL of the remote eve deployment. Pass a function to [read it at runtime](#runtime-urls). | | `description` | `string` | Yes | n/a | What the parent model reads to decide when to delegate. | | `auth` | `OutboundAuthFn` | No | none | Outbound auth from `eve/agents/auth`. | | `forwardPrincipal` | `boolean` | No | `false` | Send the calling turn's user identity to the remote deployment. See [Forwarding the caller identity](#forwarding-the-caller-identity). | | `headers` | `HeadersValue` | No | none | Request headers, static or resolved for each request. | | `path` | `string` | No | `/eve/v1/session` | Route appended to `url` to create the remote session. | | `tool` | `boolean \| "deferred"` | No | `true` | `false` lets only authored workflow tools call it, through `ctx.agent()`. `"deferred"` keeps it out of the tool list but findable with `eve__search` and callable with `eve__tool`. | ## Calling a remote agent The model calls a remote agent like a local subagent, with a `message` and an optional `taskId`. Put the full task and context in the message, because the remote agent never sees the parent's conversation. A workflow tool calls the remote agent by its file name through `ctx.agent(name)`. For structured output, pass `outputSchema` to `send()` and read the value from the response's `data`. See [Delegate work: `ctx.agent`](../tools/workflows#delegate-work-ctxagent). ## Outbound auth Use `vercelOidc()` from `eve/agents/auth` when one Vercel-deployed eve agent calls another, as in the first example. For calls between different Vercel projects, allow the calling project on the receiving agent's eve channel: ```ts title="agent/channels/eve.ts" import { vercelOidc, vercelSubject } from "eve/channels/auth"; import { eveChannel } from "eve/channels/eve"; export default eveChannel({ auth: [ vercelOidc({ subjects: [ vercelSubject({ teamSlug: "acme", projectName: "calling-agent", environment: "production", }), ], }), ], }); ``` Set `teamSlug`, `projectName`, and `environment` to the calling deployment's Vercel OIDC subject. See [subject patterns and `vercelSubject(...)`](./auth-and-route-protection#subjects-patterns-and-vercelsubject) for other environments and wildcard matching. If [Vercel Deployment Protection](https://vercel.com/docs/deployment-protection) is on for the receiving project, also allow the calling project and environment in [Trusted Sources](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/trusted-sources). Calls between projects must pass both the eve subject allowlist and Trusted Sources. ## Forwarding the caller identity Outbound auth proves which _deployment_ is calling, so by default the remote session runs as your app, not as the end user. Work that must run as the user on the remote, such as per-user [Vercel Connect](./auth-and-route-protection#tool-and-connection-auth), needs the user's identity. Set `forwardPrincipal: true` to send it: ```ts title="agent/subagents/site-ops.ts" import { defineRemoteAgent } from "eve"; import { vercelOidc } from "eve/agents/auth"; export default defineRemoteAgent({ url: "https://site-ops.example.com", description: "Executes site operations as the requesting user.", auth: vercelOidc(), // transport trust: authenticates *this* deployment forwardPrincipal: true, // identity: asserts the current session principal }); ``` - When eve creates the remote session, it sends the parent turn's `session.auth.current` and `session.auth.initiator`. When `initiator` is absent, the receiver uses `current` for both. - A follow-up with `taskId` sends the follow-up call's `session.auth.current`. The remote session keeps its original `auth.initiator`. - eve sends only identity metadata, never tokens or credentials. The receiver gets per-user credentials through its own connections. Each turn runs as its own caller, even in a child session that persists. If Alice starts the child and Bob continues it with its `taskId`, the follow-up runs with Bob as `auth.current`. If the parent turn's auth is `null`, a local child clears `auth.current`, and a remote child runs as the verified calling deployment. Neither runs as Alice. A later turn can use only the OAuth grant of its own `auth.current` user. Forwarding doesn't make a child session private to one caller: its conversation history, tool outputs, and other state persist. If they must not be visible across users, give each user a separate child session or check ownership in your application. The receiver must opt in. It names trusted deployments with `eveChannel({ trustedForwarders })` and can limit which users each one may assert (see [Auth & route protection](./auth-and-route-protection#accepting-forwarded-identity-from-another-deployment)). A refused deployment or identity gets a 403. The same trust decision covers the parent session link and, with forwarding on, trace-content limits. ## Dynamic remote agents Wrap the definition in `defineDynamic` when the target or whether to offer it depends on the session. Return `defineRemoteAgent(...)` to offer it or `null` to hide it: ```ts title="agent/subagents/weather.ts" import { defineDynamic, defineRemoteAgent } from "eve"; export default defineDynamic((ctx) => ctx.session.auth.current?.attributes.region === "us" ? defineRemoteAgent({ description: "Answers weather questions for US customers.", url: "https://us-weather-agent.example.com", }) : null, ); ``` eve runs the function before each ordinary model call. `auth` and `headers` can use its context or memo results, and they run before each outbound request. Don't store credentials in memo results. ```ts title="agent/subagents/finance.ts" import { defineDynamic, defineRemoteAgent } from "eve"; import { mintFinanceToken } from "../lib/finance"; export default defineDynamic((ctx) => { const tenant = ctx.session.auth.current?.attributes.tenant; return typeof tenant === "string" ? defineRemoteAgent({ description: "Analyzes the tenant's financial data.", url: "https://finance-agent.example.com", auth: async () => ({ headers: { authorization: `Bearer ${await mintFinanceToken(tenant)}` }, }), }) : null; }); ``` A child keeps the parent context and memo results that chose its configuration: - Later messages, answers, cancellation, ending the session, and stream reads rebuild the credentials from that original context, not from a newer caller. - If a memo result is missing, or the child's name or URL changed, the request fails before eve sends credentials. - `ctx.messages()` is unavailable during this rebuild, including when eve opens the child, so keep decisions based on the conversation inside a memo. Each message still runs as its own caller, as described in [Forwarding the caller identity](#forwarding-the-caller-identity). See [Dynamic capabilities](./dynamic-capabilities#memo-rules) for the memo rules. ## Runtime URLs eve reads a string `url` at build time. When an environment variable supplies the URL only at runtime, pass a function. It returns a string or a promise, and eve calls it when it resolves the runtime agent graph: ```ts title="agent/subagents/weather.ts" import { defineRemoteAgent } from "eve"; export default defineRemoteAgent({ url: () => process.env.WEATHER_AGENT_URL ?? "https://weather-agent.example.com", description: "Answers weather, temperature, forecast, wind, rain, and snow questions.", }); ``` The resolved `url` must be a non-empty string. To choose which agent to offer, or whether to offer one, from the current session, use [`defineDynamic`](#dynamic-remote-agents). ## Trace propagation A remote child starts its own trace with a root `invoke_agent` span, sampled by the receiving deployment. When the caller's trace context is available, the child's first turn links to the calling span with `eve.link.type=agent.dispatch`. Later turns start new traces without that link. The remote agent's local children can nest their first turn under its trace. Use `gen_ai.conversation.id` to find all turns and child sessions for one conversation. Trace context only links related work; it doesn't authorize anything. See [OpenTelemetry](../observability/otel#trace-topology) for the trace structure. The receiver accepts the parent session link only when `trustedForwarders` approves the caller. Otherwise, traces still correlate without it. On Vercel, spans from a remote agent and its local subagents carry the remote session's ID as `vercel.session_id`. The receiving project groups them as their own session. `gen_ai.conversation.id` still names the sender's conversation, and `agent.parent_run.id` names the calling session. ## Preserving trace content With `forwardPrincipal: true`, a sampled remote call forwards its audience and the most input and output content the next hop may record, as [W3C Baggage](https://www.w3.org/TR/baggage/). The receiver uses this policy only from a trusted caller: ```ts title="agent/channels/eve.ts" import { eveChannel } from "eve/channels/eve"; import { vercelOidc, vercelSubject } from "eve/channels/auth"; export default eveChannel({ auth: [vercelOidc()], trustedForwarders: (forwarder) => forwarder.subject === vercelSubject({ teamSlug: "acme", projectName: "router" }), }); ``` The request must include a callback and a valid sampled `traceparent`; `trustedForwarders` is the authorization boundary. An accepted audience replaces the one the receiver's channel would assign. The receiver combines the forwarded limit with its own trace policy. Each hop can capture less content but can't restore what an earlier hop removed. A missing, malformed, unsampled, or untrusted value falls back to metadata-only tracing. ## How remote dispatch and callbacks work A remote subagent call runs a child session on the remote deployment as a task: 1. The parent starts a conversation session on the remote's `POST /eve/v1/session` and passes a callback URL. 2. The remote accepts the child and runs its turn while the task works. 3. The callback returns the child's reply, which becomes the task's result. The parent stream shows the same `task.started`, `child.opened`, and `call.settled` events as local delegation. The callback URL must use `http` or `https` and reach the parent at a public address. The remote refuses a callback host that is, or resolves to, a private, link-local, or reserved IP address, and a refused callback fails without retries. Loopback hosts such as `localhost` and `127.0.0.1` work only when the remote runs `eve dev` or `vercel dev`. A parent and remote on a private network can't exchange callbacks. The parent's callback route takes requests without authentication, so the callback URL is the only credential. For each message to a remote agent, eve generates a random token in a workflow step of its own, and the route delivers only to a call that waits on one of those tokens. A request for any other token gets `404` with `code: "CALLBACK_NOT_PENDING"`, including the token of a hook you create with `createHook`. A callback URL carries only the message's callback capability, never the parent's deployment protection bypass secret. To let callbacks reach a parent behind Vercel Deployment Protection, configure Trusted Sources on the parent to admit the remote's project and environment. On the remote deployment, set `EVE_CALLBACK_TRUSTED_ORIGINS` to a comma-separated list of parent HTTPS origins, such as `https://parent.example.com`. Each entry is an exact origin, or starts with a `*.` label as described below. The remote attaches its own short-lived Vercel OIDC token only to those origins and to its own deployment origins. An exact entry doesn't trust other ports or subdomains. Keep the remote's Vercel OIDC token available at runtime. Callbacks don't follow redirects. Outside production, a parent's callback URL uses its generated deployment URL, which changes with every deployment. If you serve those deployments under a domain you control, trust them with a leading `*.` label, such as `https://*.preview.example.com`: - The wildcard matches exactly one label: `parent-abc123.preview.example.com`, but not `preview.example.com` or `a.b.preview.example.com`. - The port must still match. - At least two labels must follow the wildcard, and an entry with a trailing dot is rejected. - eve rejects `https://*.vercel.app`, because every Vercel deploymen - INSTRUCTIONS.md (10041 bytes)
--- name: test-audit description: "Invoke whenever writing, changing, reviewing, or sweeping tests in the eve repository. Authoring gate for new tests plus audit workflow for low-value, slow, implementation-coupled, or duplicative tests and the test-only production seams they demand." metadata: internal: true --- # Test audit Adapted from the OpenClaw [`test-audit`](https://github.com/openclaw/openclaw/blob/main/.agents/skills/test-audit/SKILL.md) skill for eve's test tiers and tooling. Three modes, one value bar. Authoring mode gates every new or changed test at write time. Audit mode runs focused sweeps of tests that re-assert source, duplicate stronger proof, couple behavior to implementation, or keep test-only production seams alive. Continue broad audits as separate coherent follow-up PRs; optimize for confidence, not deletion count. Campaign mode prunes one whole subsystem's test surface (every test file one core area or package owns); before starting one, read [CAMPAIGN.md](CAMPAIGN.md). Read the root [`AGENTS.md`](../../../AGENTS.md) testing section first. It defines eve's four tiers (unit, integration, scenario, e2e); a test belongs in the tightest tier that can express its assertion. ## Authoring gate Before adding any test, answer four questions; a missing answer means do not add it yet: 1. What observable behavior, invariant, or independent contract does it protect? 2. What credible regression makes it fail? 3. Why does existing coverage not already catch that failure? Each contract has one primary test owner at the strongest boundary; another layer needs its own distinct risk, such as a transport or lifecycle failure the owner cannot reach. Prefer extending a table-driven case or shared fixture over a near-duplicate test; consolidate duplicated setup in the same change. 4. Does it need a production seam (export, flag, wrapper, injection hook) that no production caller needs? If yes, move the test to the real boundary instead. Then check the test against every [junk pattern](#junk-patterns); a match fails the gate unless the [retention bar](#retention-bar) names the contract it independently guards. A test that would break under behavior-preserving refactoring is asserting implementation, not behavior; rewrite it at the owning boundary before landing it. Also check its cost. A scenario test that boots a dev server, installs a tarball, or runs a real build must need that subprocess, port, or bundler. If it only needs `import "eve"` to resolve or an in-memory runtime, it belongs in integration (`useTemporaryAppRoots`, `createTestRuntime`). A test that waits out a real production timeout or backoff should use fake timers or an existing public option instead of wall-clock time; do not add a test-only seam to shorten it. Bug regression tests must fail on the pre-fix code for the intended reason and pass after the owner-boundary repair. A regression test that never demonstrably failed proves the mock, not the fix. One regression at the owner boundary covers the bug; do not replay the same scenario at every layer it crosses. ## Junk patterns The shared checklist for both modes: the authoring gate rejects a new test that matches one, and audits hunt for existing tests that do. - assertion-free coverage probes; - self-comparisons and identity copiers; - copied fixtures, inventories, manifests, or export lists; - exact source, import, or string greps; - private predicate or call-shape tests duplicated at real boundaries; - duplicate invocations of the same contract, including the same scenario replayed across several dev-server or build suites; - provider-local replays of shared helpers; - tests whose only purpose is preserving test-only exports, globals, or wrappers; - dead production code whose only callers are tests; - expected values produced by the helper or renderer under test; - mocks that implement the asserted behavior, or one identical mock standing in for different APIs; - fixtures that supply the receipt, admission, or callback ordering the owner should produce, or persistence asserted against a store the path never writes; - capability tests that restate declared flags instead of exercising the delivery or acknowledgement the flag promises; - negative controls that pass for an unrelated reason, such as a denial from a different guard or a rejection the production path never reaches; - names or fixtures that promise more than the input exercises, such as a "terminates the child" test asserting only that the child never completed; - parameter matrices whose rows exercise the same code path; - suites gated on env flags or platforms that no CI job ever sets. ## Value bar Tests justify their maintenance cost by protecting behavior, a credible regression, or an independently meaningful contract. In an audit, an existing test that must change for behavior-preserving source reorganization is suspect, not automatically deletable; the authoring gate still rejects new ones. Before judging a candidate, read the complete test and production owner, its entry point, callers, callees, sibling implementations, overlapping tests, CI routing (`.github/workflows/`), and relevant history. Read root and scoped `AGENTS.md` files first. When the test claims dependency-backed behavior, inspect the dependency source or types directly. ## Discovery Keep discovery read-only and report evidence before editing. Baseline with the JSON reporter so slow files and tests are visible: ```sh pnpm --filter eve exec vitest run --config vitest.<tier>.config.ts \ --reporter=json --outputFile=/tmp/<tier>.json ``` For broad scope, run parallel discovery lanes when available, split along production owner boundaries: - core unit tests (`packages/eve/src/{execution,harness,runtime,compiler,...}`); - CLI, setup, evals, tracing, and instrumentation; - public API, client, channels, and `src/internal`; - integration tier (`*.integration.test.ts`); - scenario tier (`*.scenario.test.ts`, `packages/eve/test/scenarios/`); - other packages and apps (`packages/eve-code`, `packages/eve-catalog`, `apps/docs`, `e2e/`); - a cross-cutting pattern, test-only-export, and console-noise sweep. Outside campaign mode, prefer a few high-confidence candidates over a large speculative inventory. Hunt for the [junk patterns](#junk-patterns). ## Retention bar Keep a test when it independently enforces a public API (`eve/*` exports), protocol, config, migration, storage, security, platform, default, prompt-byte, package, release, or architecture contract. Also keep: - call ordering when order is observable behavior; - regressions with a credible failure mode; - source inspection when it is the cheapest independent guard: it fails when the contract changes (the user-facing key, byte, or path) and survives an identifier-only refactor; - a retained test that fails on the baseline: treat it as a possible product bug, reproduce it, and repair the owner rather than deleting it. Static or slow is not a deletion reason on its own. A slow test with a unique contract gets cheaper (shared boot, fake timers, lower tier), not deleted. A test that resembles implementation may still be the independent contract; prove otherwise before removing it. ## Candidate evidence Record every field below before editing. A missing field means the candidate is not ready for deletion: - exact test name and location; - what failure it can actually detect; - non-test callers of the covered production or support seam; - stronger remaining owner-boundary proof, or why no proof is needed; - relevant history and the reason the test or seam exists; - production or test-support deletion unlocked; - risk, the focused validation command, and time saved when relevant. ## Edit shape Choose one coherent owner-boundary batch. Delete obsolete test-only exports, globals, wrappers, and dead production paths instead of preserving aliases. Move retained regressions to their canonical owners. Consolidate repeated package or dependency assertions into one generic contract. Prefer net-negative production LOC. Do not add replacement tests that restate the same implementation, and do not convert uncertain candidates into cleanup to increase deletion counts. Do not commit fixture trees under `packages/eve/test/fixtures/`; scenario apps stay inline descriptors. ## Validation Never edit source or tests while Vitest is running in the checkout. 1. Run the smallest owner and sibling tests with the tier config, never bare `vitest run`: `pnpm --filter eve exec vitest run --config vitest.<tier>.config.ts <path>`. Run `pnpm --filter eve build:compiled` first if `#compiled/*` changed, and `pnpm build` before scenario runs. 2. For removed source greps or invariant assertions, run the script that owns the real contract, such as `pnpm guard:invariants`. 3. Run `pnpm fmt`, `pnpm lint`, `pnpm typecheck`, then `git diff --check`. 4. When deleted tests were the only callers of production code, `pnpm typecheck` and `pnpm lint` are the proof that nothing else depended on it. 5. Inspect `git diff --numstat`; report production/tooling separately from tests and test support. Report before and after tier timings for speed work. 6. Follow the root `AGENTS.md` changeset rule. Test-only changes need none; removing dead production code from `packages/eve` still needs one. ## Landing and continuation Commit, push, open a PR, or land only when authorized. Sign off every commit (`git commit -s`) and use the [`gh-pr-description`](../gh-pr-description/SKILL.md) skill. Land one coherent PR at a time; after landing, refresh from current `main` and rerun read-only discovery for the next high-confidence batch. ## Handoff Report: - root cause and removed low-value categories; - production owner simplifications; - retained false positives and why they remain valuable; - focused and full proof actually run, with tier timings; - production versus test LOC; - PR and merge state; - named follow-ups. - packages/eve-agent-desktop/AGENTS.md (1581 bytes)
# @eve/agent-desktop Extension Package This published package is the `@eve/agent-desktop` extension: accessibility-based desktop tools backed by the agent-desktop CLI, plus the `@eve/agent-desktop/sandbox` helpers that install and start the desktop. Before writing code, read the installed eve package docs for extensions, tools, and sandboxes as applicable. ## Boundaries - Each tool wraps one agent-desktop command; the CLI's argument surface is the contract, checked by `test/scenario/conformance.test.mjs`. - Install only in the consumer's sandbox `prepare` through `installAgentDesktop`. Tools never install at tool time; they probe the version, restart a desktop a resumed sandbox lost, and fail with setup guidance otherwise. Bump `AGENT_DESKTOP_REVALIDATION_KEY` inputs when the install changes. - Keep `extension/lib/sandbox.ts` and `extension/lib/process.ts` free of other extension imports; they are published as `@eve/agent-desktop/sandbox`. - Keep shared implementation under `extension/lib/`; filesystem paths define tool names. ## Tests Tests run against the built `dist/`, so there is no unit tier. Tiers are set by directory: - `test/integration/`: tools and helpers with in-memory fake sandboxes. - `test/scenario/`: real subprocesses. `conformance.test.mjs` needs the agent-desktop CLI (`AGENT_DESKTOP_BIN` or on `PATH`) and `live.test.mjs` needs `AGENT_DESKTOP_LIVE=1` on Ubuntu 24.04+ with sudo; both skip otherwise. - `test/support/`: shared helpers, not tests. Run typecheck, build, both tiers, lint, and package-scoped formatting before completion.
- packages/eve-board/AGENTS.md (1652 bytes)
# @eve/board This published package brings Vercel Board to eve agents: a channel, board tools, watch tools, and a `collaborate` skill, built with `eve extension build`. ## Boundaries - Watches are created, listed, and removed only by the `watch`, `watches`, and `unwatch` tools. The channel and its wake route never write the board registration, and nothing runs at startup. - A watch is a watcher ID shared by two board records: the registration holds what it matches, and a labeled `noSync` root in the watch channel holds what it does. The watch's ID and action live in that message's text, never only in labels, which anyone with label access can change. Keep no other watch store. - `can` narrows model-facing calls and claims. Registration, watch records, the lock, pulls, acks, and claim settlement use the deployment's handle, because the board refuses them to a narrowed one. - Keep claim tokens out of channel metadata, which reaches instrumentation. Task tools return the settlement, and the channel performs it. - Registration changes read, modify, and write the whole registration under the board lock task, so concurrent sessions and replicas never drop each other's watchers. - Talk to the board only through `extension/lib/client.ts`, which wraps `@vercel/board` in eve-owned types. - Read `extension.config` lazily, inside `execute` or a thunk, so a tool re-exported without a mount falls back to defaults. - Import only public `eve/*` entry points and `eve/internal/channels`. ## Build and test Run `pnpm --filter @eve/board typecheck`, `test`, and `build`. The tests run against an in-memory `@vercel/board` and need eve built.
- packages/eve-code/AGENTS.md (2305 bytes)
# @eve/code Extension Package This private package is the source of the `eve/extensions/code` extension for CLI-based coding work. It contributes investigation and review skills, instruction fragments, Connect-backed authentication hooks, and consumer sandbox helpers. Before writing code, read the installed eve package docs for extensions, hooks, tools, skills, subagents, and sandboxes as applicable. ## Boundaries - Connector UIDs enter through extension config. The authentication hook resolves Vercel app tokens before each turn. - GitHub instructions, the `pr` skill, and the `gh` tool belong to `@eve/git` (`eve/extensions/git`). The removed `github` config is rejected; do not add GitHub or pull request contributions here. - Consumers with non-Connect credentials may call `authenticateGitHub` or `authenticateVercel` directly from their sandbox lifecycle. - Broker credentials without placing them in model-authored URLs or arguments. - Use real `git`, `gh`, and `vc` CLIs rather than bespoke repository lifecycle tools. - Do not mount file or search tools. eve's default `bash`, `read_file`, `write_file`, and `edit_file` cover file work, and the instructions point the model at `rg` and `find` in `bash`, as pi does. - Delegation uses eve's built-in `agent` tool. The removed `worker` config is rejected with a migration hint; do not add an extension-owned worker subagent back. - Keep shared implementation under `extension/lib/`; filesystem paths define contribution names. - Computer use lives in `@eve/computer-use` (`eve/extensions/computer-use`). Import its public helpers directly; do not add computer-use code or re-exports here. ## Build and publish The eve build copies `extension/` into `packages/eve/src/extensions/code/extension` and compiles it into the `eve` package; public entry points are declared in `packages/eve/package.json` and `packages/eve/src/extensions/code/`. Do not publish this package or add it as an eve dependency (it depends on eve). Import only public `eve/*` APIs from `extension/`; third-party imports are bundled into eve's dist. Keep tests under `test/unit/`, `test/integration/`, and `test/scenario/`, outside the discovered extension tree. Run typecheck, all three test tiers, eve's build, lint, and package-scoped formatting before completion.
- packages/eve-computer-use/AGENTS.md (1236 bytes)
# @eve/computer-use Extension Package This private package is the source of the `eve/extensions/computer-use` extension. It contributes the `computer_use` tool and the sandbox helpers that install and start the desktop and driver. Before writing code, read the installed eve package docs for extensions, tools, and sandboxes as applicable. ## Boundaries - Keep this extension free of coding tools; those belong in `@eve/code`. - Keep shared implementation under `extension/lib/`; filesystem paths define contribution names. - Keep the sandbox exports in `extension/lib/sandbox.ts`; `@eve/code` re-exports them for compatibility. ## Build and publish The eve build copies `extension/` into `packages/eve/src/computer-use/extension` and compiles it into the `eve` package; public entry points are declared in `packages/eve/package.json` and `packages/eve/src/computer-use/`. Do not publish this package or add it as an eve dependency (it depends on eve). Import only public `eve/*` APIs from `extension/`; third-party imports are bundled into eve's dist. Keep tests under `test/scenario/`, outside the discovered extension tree. Run typecheck, the scenario tests, eve's build, lint, and package-scoped formatting before completion.
- packages/eve-custom-skills/AGENTS.md (1884 bytes)
# @eve/custom-skills Extension Package This private package is the source of the `eve/experimental/extensions/custom-skills` extension. It lets the people talking to an agent save their own versioned skills, personal or shared with everyone in a channel or group chat, and applies them on later turns. Before writing code, read the installed eve package docs for extensions, tools, skills, instructions, and memory as applicable. ## Boundaries - `extension/lib/lifecycle.ts` is storage-independent: it talks only to `SkillRepository`. Keep validation, drafts, publish, rollback, modes, and limits there. - `extension/lib/tool-support.ts` builds each changing tool's approval and execution from one planner, so the approval rule judges exactly what the tool runs. Keep approval logic in `lib/approval.ts`. - `extension/lib/public/` holds the files published as `eve/experimental/extensions/custom-skills/policies` and `/repository`. - Storage details belong in a repository. `document-repository.ts` stores skills in an eve memory document backend; consumers can pass their own `repository` instead. - Tools address skills by their normalized name. Keep tool names bare (`create`, not `create_skill`); the mount supplies the namespace. - Keep shared implementation under `extension/lib/`; filesystem paths define contribution names. ## Build and publish The eve build copies `extension/` into `packages/eve/src/extensions/custom-skills/extension` and compiles it into the `eve` package; the public entry point is declared in `packages/eve/package.json`. Do not publish this package or add it as an eve dependency (it depends on eve). Import only public `eve/*` APIs from `extension/`. Keep tests under `test/unit/` and `test/integration/`, outside the discovered extension tree. Run typecheck, both test tiers, eve's build, lint, and package-scoped formatting before completion.
- packages/eve-git/AGENTS.md (1665 bytes)
# @eve/git Extension Package This private package is the source of the `eve/extensions/git` extension. It owns everything GitHub-facing: the pull request skill, GitHub instructions, and, with `github` config, the Connect-brokered `gh` tool and signed-commit workflow. Before writing code, read the installed eve package docs for extensions, tools, skills, instructions, and sandboxes as applicable. ## Boundaries - Without `github` config, contribute no tools: agents use the `gh` and `git` CLIs from their own shell. Never tell them shell credentials are unavailable. - With `github` config, the `gh` tool leases a repository-scoped GitHub token per invocation. Broker credentials without placing them in model-authored URLs or arguments. - Keep GitHub and pull request content here, not in `@eve/code`. Shared tooling sources used by `@eve/code` are exposed through `eve/internal/git`, not the public sandbox API. - Keep shared implementation under `extension/lib/`; filesystem paths define contribution names. ## Build and publish The eve build copies `extension/` into `packages/eve/src/extensions/git/extension` and compiles it into the `eve` package; public entry points are declared in `packages/eve/package.json` and `packages/eve/src/extensions/git/`. Do not publish this package or add it as an eve dependency (it depends on eve). Import only public `eve/*` APIs from `extension/`; third-party imports are bundled into eve's dist. Keep tests under `test/unit/`, `test/integration/`, and `test/scenario/`, outside the discovered extension tree. Run typecheck, all three test tiers, eve's build, lint, and package-scoped formatting before completion.
- packages/eve-self-improvement/AGENTS.md (1057 bytes)
# @eve/self-improvement Read the root AGENTS.md, CONTRIBUTING.md, and this package README before changes. Use the workspace Node and pnpm versions. Read docs/extensions/index.md before changing the extension contract. Keep runtime contributions and public entries in extension/ so they share one compiled module graph; isolated regressions belong in test/integration/. Run the package typecheck, integration tests, build, and packed-consumer scenario when changing installation or exports. Private Blob is the default store. The optional Postgres adapter preserves existing ledgers; never switch an existing backend on errors. Keep credentials, transcripts, operator records, and production fixtures out of source and reports. Only the real scheduled runtime identity can start a cycle. Candidate sandboxes have no publishing or production authority. Preserve fenced recovery, independent verification, required checks, signed commits, and the trusted release boundary. Installing or building this package starts no job; the host mounts and deploys it.
- packages/eve/src/internal/nitro/AGENTS.md (1883 bytes)
# Nitro host foundation invariants eve's Nitro host is built from one typed host spec, one ordered plugin list, and one route table. Review and `pnpm guard:invariants` enforce these rules: 1. **Nitro is configured from data.** One adapter turns a typed host spec into the `NitroConfig` passed to `createNitro`. Nothing writes `nitro.options` afterward. The only hooks eve uses are declared in that config: the `build:before` entry wrapper and `build:config` edits that public options can't express. No `rollup:before`. 2. **Development and production differ by data, not code paths.** One spec function covers both. 3. **One ordered, filtered plugin list per build.** - Every eve build plugin uses hook `filter`s, except where it truly needs every id. - Authored-source builds share one plugin factory. - Nothing patches a third-party plugin or rewrites Nitro's generated modules. 4. **Generated code carries data through `text:` or `bytes:` imports,** never as inlined JS literals, so Nitro's `replace` can't touch it. 5. **Every eve-owned Nitro id uses `#eve/`.** No `#nitro/` ids, no ad hoc prefixes. Route and task virtual module ids end in `.mjs`, because the bundler infers module type from the id's extension and an id can embed an authored route path (#5742). 6. **eve never lets Nitro resolve or install a dependency.** Rolldown comes through `deps.paths`. Storage and database runtimes are rejected in authored code. 7. **Post-build output rewriting is a named, shrinking list.** Each entry is tied to an upstream ask, and new entries need justification. 8. **Development host builds are one-shot.** eve configures no watchers, watch options, or reload hooks on Nitro. 9. **Tests protect behavior.** No test pins private Nitro ids or hook names, or calls Nitro hooks by hand. Production code has no seams that exist only for tests.
- README.md (4924 bytes)
<div align="center"> <a href="https://eve.dev/"> <picture> <source media="(prefers-color-scheme: dark)" srcset=".github/assets/eve.svg"> <img alt="eve logo" src=".github/assets/eve.svg" height="128"> </picture> </a> <h1>eve</h1> <a href="https://vercel.com"><img alt="Vercel logo" src="https://img.shields.io/badge/MADE%20BY%20Vercel-000000.svg?style=for-the-badge&logo=Vercel&labelColor=000"></a> <a href="https://www.npmjs.com/package/eve"><img alt="NPM version" src="https://img.shields.io/npm/v/eve.svg?style=for-the-badge&labelColor=000000"></a> <a href="https://github.com/vercel/eve/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/npm/l/eve.svg?style=for-the-badge&labelColor=000000"></a> <a href="https://github.com/vercel/eve/discussions"><img alt="Join the community on GitHub" src="https://img.shields.io/badge/Join%20the%20community-blueviolet.svg?style=for-the-badge&logo=Github&labelColor=000000&logoWidth=20"></a> </div> [eve](https://eve.dev/) is a filesystem-first framework for durable AI agents. Core agent capabilities live in conventional locations, so projects are easier to inspect, extend, and operate. ## The filesystem is the authoring interface A typical eve agent has this structure: ```text my-agent/ └── agent/ ├── agent.ts # Optional: model and runtime config ├── instructions.md # Required: the always-on system prompt ├── tools/ # Optional: typed functions the model can call │ └── get_weather.ts ├── skills/ # Optional: procedures loaded on demand │ └── plan_a_trip.md ├── channels/ # Optional: message channels (HTTP, Slack, Discord) │ └── slack.ts └── schedules/ # Optional: recurring cron jobs └── weekly_recap.ts ``` Read the [documentation](https://eve.dev/docs) for the full project layout and guides. ## Quick start ```bash npx eve@latest init my-agent ``` This creates a new `my-agent` directory, installs its dependencies, initializes Git, and starts the interactive terminal UI. The generated agent uses `openai/gpt-6-luna-fast` with high reasoning. To start with another AI Gateway model, pass its model ID: ```bash npx eve@latest init my-agent --model openai/gpt-5.6-terra ``` Passing `--model` without `--reasoning` uses the provider's default reasoning. Pass `--reasoning` to set it explicitly. To add eve to an existing project, pass a path: ```bash cd myapp npx eve@latest init . ``` > [!NOTE] > The `eve` package includes its full documentation, so coding agents can read it locally from > `node_modules/eve/docs`. ### A minimal example The generated project includes an `agent` directory. Replace `agent/instructions.md` with: ```md You are a concise weather demo assistant. Tell users that the weather data is mocked. ``` Add a mock weather tool at `agent/tools/get_weather.ts`: ```ts import { defineTool } from "eve/tools"; import { z } from "zod"; export default defineTool({ description: "Return mock weather data for a city.", inputSchema: z.object({ city: z.string().min(1) }), async execute({ city }) { return { city, condition: "Sunny", temperatureF: 72 }; }, }); ``` Choose the model in `agent/agent.ts`: ```ts import { defineAgent } from "eve"; export default defineAgent({ model: "openai/gpt-6-luna-fast", reasoning: "high", }); ``` For a new scaffold, start the agent again: ```bash npm run dev ``` That's a working agent. Add human-in-the-loop prompts, subagents, and schedules as needed. ### Add Web Chat From your agent's directory, link a Vercel project and add Web Chat: ```bash npx eve link npx eve add channel/web ``` Choose a hosting layout, then **Sign in with Vercel** to provision authentication for members of the project's team. You can also select **Web Chat** from the terminal UI's `/add` channel picker. Run `npx eve deploy` when ready to publish. Local development works without browser sign-in. See the [Web Chat setup guide](https://eve.dev/docs/channels/eve#web-chat-with-sign-in-with-vercel) for permissions and recovery. ## Community The eve community lives on [GitHub Discussions](https://github.com/vercel/eve/discussions), where you can ask questions, share ideas, and show what you've built. ## Contributing Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) to get the repo running locally and land a change, and use [issues](https://github.com/vercel/eve/issues) and [discussions](https://github.com/vercel/eve/discussions) to collaborate. By participating, you agree to our [Code of Conduct](CODE_OF_CONDUCT.md). ## Security Please do not open public issues for security vulnerabilities. Instead, follow [SECURITY.md](SECURITY.md) and report responsibly to [[email protected]](mailto:[email protected]). - SKILL.md (3073 bytes)
--- name: gh-pr-description description: Drafts and reviews GitHub pull request descriptions for the eve repository. Use when opening, updating, or reviewing a PR, or when summarizing a branch for reviewers. metadata: internal: true --- # GitHub PR description Inspect the branch diff, commits, related issue or discussion, tests, docs, and changesets. When updating a PR, read its current body first. ## Write Fill in the Summary and Changes sections of `.github/pull_request_template.md`. Never add a Validation, Test plan, or Checklist section, and delete them from an existing body when you update it. Write for a reviewer, not a changelog. Follow these ASD-STE100 rules where they apply: - Use approved words from the ASD-STE100 dictionary, with one meaning per word. - Use active voice and keep one topic in each sentence. - Limit descriptive sentences to 25 words and procedural sentences to 20 words. - Keep necessary technical terms, proper nouns, and code identifiers. ### Summary - Keep it to one short paragraph: usually 2–4 sentences and about 100 words or fewer. - Lead with the concrete problem, user need, or decision behind the change, then state the approach in a sentence or two. Leave the specifics to Changes. - Link an existing issue or discussion with `Closes #N`, `Related to #N`, or an equivalent when one exists. Do not create an issue solely for a PR. ### Changes A flat list of the changes a reviewer must know, not a narrative. - Put public API changes first: new, changed, or removed exports, options, config fields, CLI commands and flags, events, defaults, and error types. Then list other user-visible behavior changes. - Write one change per bullet, in one sentence where possible. Name the identifier in code format and its entry point when it has one, such as `renderInteractionBlocks()` from `eve/channels/slack`. - Add a short reason with "so" or "because" only when the Summary does not already make it clear. - Prefix breaking changes with `Breaking:` and say what callers must change. - End with preserved behavior, scope boundaries, or follow-ups only when they matter to review. - Usually 2–6 bullets. A one-change PR gets one bullet. Do not nest bullets, add sub-headings, or split the list by commit or original PR. - Do not list files, internal refactors, tests, or checks you ran. Include implementation detail only when it is necessary to assess behavior or risk. Example, from #5733: ```md ### Changes - Scaffolded projects now default to `@vercel/[email protected]` through `DEFAULT_CONNECT_PACKAGE_VERSION`. - The optional `@vercel/connect` peer is now `^2.7.0`, so npm won't pair eve with a connect release that rejects it. - Templates under `apps/templates` are unchanged. They pin stable eve releases, which older connect releases already accept. ``` ## Publish Before publishing, confirm the Summary leads with why the change is needed and Changes lists every public API change. Write the body to a file, then pass it to `gh pr create` or `gh pr edit` with `--body-file`.