eve-agent-architect

name	eve-agent-architect
description	Design, build, secure, evaluate, and ship production-grade Vercel Eve agents from Pi. Use when the user wants to create, plan, improve, or audit an Eve agent; map requirements to Eve tools, skills, connections, channels, schedules, subagents, sandbox, auth, approvals, and evals; or migrate from a demo agent to a durable production agent.
compatibility	Pi coding agent; Eve beta projects. Always verify exact Eve APIs against node_modules/eve/docs for the installed version.

Eve Agent Architect for Pi

Use this skill to take a user from “I need an agent that does X” to a working, secure, eval-covered Eve agent. This is a Pi-native methodology skill: it tells Pi how to inspect the filesystem, interview the user, design behavior before features, implement incrementally, and verify with Eve’s local docs and CLI.

Non-negotiables

1. Never invent Eve APIs. Eve moves fast. Before writing or changing Eve code, read the installed docs at node_modules/eve/docs/README.md and any linked docs for the surfaces you will use. If Eve is not installed, scaffold first, then read bundled docs.
2. Do not skip behavior design. Good agents come from scenario traces, not feature shopping. Trace 2–4 core scenarios before choosing Eve files.
3. No orphan features. Every tool, connection, skill, channel, schedule, state slot, hook, or subagent must trace back to a scenario step or explicit safety requirement.
4. Safety before real data. Any sensitive or irreversible action needs code validation, tenant scoping, idempotency, and/or human approval before it can ship.
5. Evals are part of done. Each core trace becomes an eval. Include at least one negative eval and one approval/resume eval when approvals exist.
6. Use Pi correctly. Prefer read for files, bash for discovery (rg, find, ls), and edit for exact targeted edits. Avoid dumping large files through shell when read works.

Reference files bundled with this skill:

• references/pi-eve-workflow.md — Pi-specific execution loop, filesystem detection, commands, and artifacts
• references/eve-surface-map.md — decision guide for mapping requirements to Eve surfaces
• references/security-and-trust.md — threat model, auth, approvals, sandbox, data, tenancy, cost controls
• references/evals-and-quality.md — eval strategy, deterministic tests, CI and release gates
• templates/design-brief.md — persistent design artifact to write into the project

Phase 0 — Detect the starting point before asking questions

Inspect the current directory first. Do not ask the user for facts the filesystem can answer.

Run discovery with safe commands:

pwd
find . -maxdepth 3 \( -name package.json -o -name agent.ts -o -name instructions.md -o -path './agent/*' -o -path './node_modules/eve/docs/README.md' \) -print | sort

Then classify:

Found	Treat as
node_modules/eve/docs/README.md	Eve installed; read docs and run npm ls eve or package-manager equivalent
agent/instructions.md or agent/agent.ts	Existing Eve agent; inventory and harden/extend, do not greenfield blindly
package.json but no agent/ and no Eve	Existing app; candidate for eve init . after confirmation
Empty/unrelated directory	Candidate for npx eve@latest init <name> in a new folder
Ambiguous monorepo	Ask where the Eve app should live

If an Eve project exists, run eve info after reading docs. If eve is not on PATH, use the local binary (npx eve info) after dependencies are installed.

Phase 1 — Interview once, then summarize the agent spec

Ask only missing questions, batched in one round. If ask_user_question exists, use it; otherwise ask in chat.

Required information:

1. Job: What exactly should the agent accomplish? What is a successful end-to-end interaction?
2. Users and surfaces: Web app, HTTP API, Slack/Discord/Teams/Telegram/Twilio, GitHub, Linear, cron, or service-to-service?
3. Integrations: Databases, SaaS APIs, MCP servers, OpenAPI specs, private services, files, code execution?
4. Identity model: Shared app identity, per-user OAuth, app+user mixed, multi-tenant?
5. Risk: Payments, messages/emails, deletes, production writes, regulated data, PII, secrets, prompt-injection risks?
6. Cadence: Reactive only, scheduled/background, multi-turn durable workflows?
7. Runtime needs: Sandbox code/shell/file work, long analysis, large documents, network access?
8. Hosting: Vercel default or self-hosted Node? Preview/prod environments?
9. Acceptance bar: What behavior would convince the user this is useful? What must never happen?

Return a one-paragraph spec plus a bullet list of explicit assumptions. Get confirmation before Phase 2 unless the user already gave clear requirements and asked you to proceed.

Phase 2 — Design behavior before selecting Eve features

Work in templates/design-brief.md shape. For non-trivial projects, create or update docs/eve-agent-design.md with the design as it evolves.

2.1 Trace 2–4 core scenarios

Write concrete numbered traces with real example data:

• happy path
• sensitive/irreversible path
• ambiguous/messy user request
• background/scheduled path, if applicable

Each trace must include:

• inbound surface and example payload/message
• authenticated identity and tenant context
• what the agent knows at that moment
• every action/tool/connection call with example input and output
• decision points and who owns them: model, code, or human
• where it pauses for approval or clarification
• idempotency/retry behavior
• final response and channel

Bad trace: “The agent processes the refund.” Good trace: “It calls lookup_charge with { chargeId: 'ch_123', tenantId: 't_acme' }; code scopes the query by tenant and returns { amount: 7500, currency: 'usd', refundable: true }.”

2.2 Derive contracts from traces

Build tables for:

• tools/connections: name, purpose, input, output, side effect class, approval policy, idempotency key, system touched
• decisions: branch, owner, enforcement mechanism
• data flow: enters model, stays in app runtime, enters sandbox, leaves system, never exposed
• failures: tool error, replay, duplicate side effect, user ambiguity, prompt injection, over-budget, out-of-scope request

Cut anything not used by a trace or safety requirement.

2.3 Sign-off checkpoint

Present:

• scenario traces
• tool/connection contract table
• decision-owner table
• data-flow notes
• failure answers
• open assumptions

Ask for sign-off or edits. Do not start writing Eve files until the design is stable unless the task is a small fix to an existing agent.

Phase 3 — Map the design to Eve architecture

Use references/eve-surface-map.md. Produce a proposed tree, with each file tied back to a trace step or safety requirement.

Default mapping rules:

Need	Eve surface
Always-on identity/rules/refusals	agent/instructions.md
Runtime config/model/limits	agent/agent.ts
Typed code action	agent/tools/<snake_case>.ts
Existing MCP/OpenAPI service	agent/connections/<name>.ts preferred over hand-rolled tools
Occasionally needed runbook	agent/skills/<name>.md
Slack/GitHub/Linear/etc.	agent/channels/<name>.ts
Web/custom HTTP	default Eve HTTP channel or custom defineChannel
Scheduled/background work	agent/schedules/<name>.ts or .md
Specialist with distinct prompt/tool surface	agent/subagents/<id>/ only when a skill is insufficient
Sandbox file/code/shell work	built-in sandbox tools; customize agent/sandbox/ only for setup/network/backend
Per-user/tenant capabilities	dynamic capabilities/auth-scoped tools
Audit/metrics	agent/hooks/<name>.ts observe-only
Behavior correctness	evals/*.eval.ts

Add explicit cost and blast-radius controls to the plan: token limits, subagent depth, tool budgets, network policy, and approvals.

Phase 4 — Build incrementally in Pi

Follow references/pi-eve-workflow.md.

Recommended order:

1. Scaffold or install Eve only after confirming project location.
2. Read installed Eve docs completely enough for the surfaces you will author.
3. Create minimal agent/instructions.md and agent/agent.ts with limits.
4. Add one read-only tool or connection; verify.
5. Add write/sensitive actions with validation, idempotency, and approval; verify.
6. Add channel/schedule/subagent/sandbox customization one at a time.
7. Add evals as soon as a trace is runnable.
8. Run eve info, typecheck, evals, and build before calling it done.

Verification loop after each meaningful addition:

eve info
npm run typecheck --if-present
npm test --if-present
eve eval --strict

Use the package manager that exists in the project (package-lock.json, pnpm-lock.yaml, bun.lock, yarn.lock). If commands differ, infer from package.json scripts.

Phase 5 — Security hardening gate

Before real data or traffic, use references/security-and-trust.md and verify:

• route auth is real; no scaffold placeholder in production
• tenant/user identity is derived from verified auth, not request body text
• every sensitive write has approval or code-enforced policy
• non-idempotent side effects have idempotency keys or approval gates
• sandbox egress is intentional, not accidental allow-all
• unnecessary built-in tools are disabled or wrapped
• tool outputs are minimized/redacted
• secrets are not in source, .eve/, logs, eval fixtures, or sandbox files
• unauthenticated prod request returns 401 where expected

Phase 6 — Evals, CI, and release

Use references/evals-and-quality.md.

Minimum suite:

• one smoke eval per core happy path
• one negative eval proving the agent does not act out of scope
• one approval pause/resume eval per approval-gated class of action
• one cross-tenant or auth-boundary eval if multi-tenant/per-user
• deterministic runtime tests or fixture mocks for tool plumbing where possible

Release gate:

eve info
eve eval --strict
eve build

For Vercel deploys: eve deploy, then verify preview/prod with eve dev <url> and auth probes. For self-hosting: eve build && eve start with explicit sandbox backend and route auth.

Phase 7 — Leave the next agent smarter

At the end, update project memory/artifacts:

• docs/eve-agent-design.md — final design and trace matrix
• docs/eve-security-review.md — checklist results and residual risks
• docs/eve-eval-plan.md — eval coverage and gaps
• README or runbook with local dev, eval, deploy, and required env vars

Final response to the user should include:

• what was built/changed
• key safety decisions
• verification commands run and results
• remaining risks or assumptions
• exact next step

When to be stricter than the user asked

If the user asks for a quick demo, keep it small but still mark what is unsafe for production. If they mention customers, payments, production data, multi-tenant SaaS, or external messaging, require the full security and eval gates before “done.”