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 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 moves every item through four declared subagent stations in order: classifier (triage, fast model) → 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). 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 for the component map, data flow, trust model, and boundaries.

Setup & commands

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 validate       # check + typecheck + eve info in one command

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 factory/* pull requests, unattended, with the fix loop capped by counting attempt comments on the PR thread; 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(), 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 nothing from the root (no instructions, skills, connections, tools, or sandbox), so the orchestrator packs everything 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: one kept snapshot and a 14-day expiration, so template snapshots survive quiet stretches without accumulating. 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 reached through a generic file operation; add a namespace there, never as a loose constant in a feature module.
• 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 under the reserved user-preferences/ Blob prefix, reachable only through the principal-scoped preference tools.
• The shared factory brain derives its key from FACTORY_REPO, never from model input or a caller principal — see agent/lib/factory-brain.ts. It lives under the reserved factory-brain/ Blob prefix, reachable only through read_factory_brain / update_factory_brain; writes are gated by factoryBrainPolicy (unattended runs denied, trusted callers direct, everyone else parks) so an untrusted issue body can't poison the context every future run reads.
• Handoff artifacts live under the reserved artifacts/ Blob prefix, reachable only through save_artifact / read_artifact — see agent/lib/artifacts/config.ts. Ids are model-supplied on read, so every id must pass the anchored ARTIFACT_ID_PATTERN (no dots or slashes) before it is interpolated into a Blob key; that is what keeps a station from addressing the brain or a preference file through the artifact tools. Saves never overwrite and are size-bounded, which keeps both tools inert enough to live ungated inside a station.

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.