| 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
- 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.
- Do not skip behavior design. Good agents come from scenario traces, not feature shopping. Trace 2–4 core scenarios before choosing Eve files.
- 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.
- Safety before real data. Any sensitive or irreversible action needs code validation, tenant scoping, idempotency, and/or human approval before it can ship.
- 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.
- 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 artifactsreferences/eve-surface-map.md — decision guide for mapping requirements to Eve surfacesreferences/security-and-trust.md — threat model, auth, approvals, sandbox, data, tenancy, cost controlsreferences/evals-and-quality.md — eval strategy, deterministic tests, CI and release gatestemplates/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:
- Job: What exactly should the agent accomplish? What is a successful end-to-end interaction?
- Users and surfaces: Web app, HTTP API, Slack/Discord/Teams/Telegram/Twilio, GitHub, Linear, cron, or service-to-service?
- Integrations: Databases, SaaS APIs, MCP servers, OpenAPI specs, private services, files, code execution?
- Identity model: Shared app identity, per-user OAuth, app+user mixed, multi-tenant?
- Risk: Payments, messages/emails, deletes, production writes, regulated data, PII, secrets, prompt-injection risks?
- Cadence: Reactive only, scheduled/background, multi-turn durable workflows?
- Runtime needs: Sandbox code/shell/file work, long analysis, large documents, network access?
- Hosting: Vercel default or self-hosted Node? Preview/prod environments?
- 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:
- Scaffold or install Eve only after confirming project location.
- Read installed Eve docs completely enough for the surfaces you will author.
- Create minimal
agent/instructions.md and agent/agent.ts with limits.
- Add one read-only tool or connection; verify.
- Add write/sensitive actions with validation, idempotency, and approval; verify.
- Add channel/schedule/subagent/sandbox customization one at a time.
- Add evals as soon as a trace is runnable.
- 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 matrixdocs/eve-security-review.md — checklist results and residual risksdocs/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.”
