create-agent

Turn a rough agent idea into a runnable eve agent through structured Q&A, a written brief, then scaffold + implementation.

Phases

Task Progress:
- [ ] Phase 1 — Design interview (one question at a time)
- [ ] Phase 2 — Write agent/EVE-BRIEF.md and get confirmation
- [ ] Phase 3 — Scaffold eve, implement, verify

Do not skip Phase 1 or Phase 2. Do not scaffold or write agent code until the user confirms the brief.

---

Phase 1 — Design interview

Interview the user until you have a shared, implementable picture of the agent.

Rules

1. One question at a time. Wait for the user's answer before the next question.
2. Include a recommended answer with every question — state your pick and why in one or two sentences.
3. Explore instead of asking when the answer is in the repo, docs, or env (existing agents, package.json, API keys, monorepo layout).
4. Follow the decision tree. Resolve blockers before dependent questions (purpose → surfaces → tools → scope → runtime).
5. Use concrete scenarios. When behavior is fuzzy, invent a user message and ask what the agent should do step by step.
6. Tighten vague language. Replace overloaded words ("handle", "manage", "process") with specific capabilities or tool names.
7. Surface contradictions. If a new answer conflicts with an earlier one, call it out before moving on.

What to cover (in rough order)

Area	Goal
Purpose	One sentence: what job does this agent do?
Users & entry	Who talks to it, and through what channel(s)?
Core loop	Typical turn: user says X → agent does Y → user sees Z
Eve surfaces	Which slots matter? (tools, skills, channels, connections, subagents, schedules, hooks, sandbox, evals)
Tools & data	Named capabilities, inputs/outputs, real APIs vs connections
Scope	What is deliberately out of scope for v1?
Model	Preferred model string (default: openai/gpt-4.1-mini via AI Gateway)
Secrets	Env vars needed for real integrations (always include AI_GATEWAY_API_KEY)
Location	Project directory name and whether it lives inside an existing monorepo

Stop interviewing when you can fill every section of EVE-BRIEF template without guessing.

End Phase 1

Summarize decisions in a short bullet list. Ask: "Does this match what you want? Ready for me to write EVE-BRIEF.md?"

---

Phase 2 — EVE-BRIEF.md

Write agent/EVE-BRIEF.md using the template in reference.md.

• If eve is not scaffolded yet, write the brief to a temp path or describe that it will land at agent/EVE-BRIEF.md after init — then place it there immediately after scaffold.
• After writing, show the brief and ask for explicit confirmation before Phase 3.
• Record any mock/stub fallback and the reason in the brief's data-source column.
• Fill the Teaching comments section (which surfaces get annotated, primary "start here" files for the README table).

---

Phase 3 — Scaffold, implement, verify

0. Read eve docs (required before any implementation)

After eve is installed, must read bundled docs at node_modules/eve/docs/ before writing agent code:

1. Introduction and Getting Started
2. Every surface page listed in the brief (tools, channels, connections, etc.)
3. Any API or pattern referenced by sibling agents in the repo

Never rely on hardcoded snippets from this skill or training memory. API shapes, imports, and conventions change — local docs are the source of truth. See reference.md.

1. Detect project layout

Before scaffolding, inspect the repo:

Situation	Action
No agent/ directory anywhere	npx eve@latest init <dir> (standalone) or npx eve@latest init . (add to existing app)
One existing eve agent	Mirror its project structure (package.json scripts, tsconfig, env pattern)
Multiple eve agents (monorepo)	Inventory siblings; mirror naming, workspace deps, and folder conventions from the nearest agent

Do not assume a specific monorepo shape. Discover conventions from the codebase. See reference.md.

2. Install / scaffold

No eve project yet:

npx eve@latest init <agent-dir>

init installs deps and may start the dev server — run in a controllable process and stop the server before editing files.

Existing project, no agent/ directory:

cd <project-root>
npx eve@latest init .

eve already present: skip init; ensure agent/agent.ts and agent/instructions.md exist.

Optional: --channel-web-nextjs only when the user asked for Web Chat and they are using Next.js.

3. Place EVE-BRIEF.md

Write or move agent/EVE-BRIEF.md into the scaffolded agent/ directory.

4. Implement from the brief

Minimum bar for every agent:

• agent/agent.ts — model config per brief (follow docs for current defineAgent API)
• agent/instructions.md — identity, when to use tools, tone, guardrails from the brief
• At least one real capability — tools, connections, or other surfaces from the brief
• Channel config if the brief requires it
• .env.example with AI_GATEWAY_API_KEY= and every env var for real integrations
• README with clone-and-run steps

Implement only surfaces listed in the brief. For each surface, read the matching page in node_modules/eve/docs/ and follow patterns from the nearest existing agent in the repo when one exists.

Teaching comments (required):

Every file you create or substantially edit during scaffold + implementation must include verbose, educational comments that teach the user how eve works — not just what the line does. Treat the generated agent as a guided tutorial the user will read while running it.

See reference.md — Teaching comments for the full checklist. At minimum:

• File header on every agent/**/*.ts file: which eve surface this file belongs to, how eve discovers/loads it, and what role it plays in a turn.
• Section blocks before each logical unit (imports, schema, handler, export): explain the eve concept (e.g. tool identity from path, defineAgent slots, channel request lifecycle).
• Inline comments on eve-specific APIs, config keys, and conventions the user would not know from TypeScript alone — link to the matching doc page under node_modules/eve/docs/ when helpful.
• instructions.md: short callouts above each major section explaining how system instructions shape model behavior in eve.
• README: a "How this agent is structured" section that maps files → eve surfaces and points to the most-commented files to read first.

Do not strip comments eve init generated if they teach a concept. Prefer adding over removing. Skip comments only on truly obvious TypeScript (e.g. import of a local type). Never use placeholder comments like // TODO: explain — write the explanation.

Conventions:

• Always eve, never Eve
• Tool identity is path-derived: agent/tools/foo.ts → foo
• Prefer real connections (agent/connections/) and real data/APIs when feasible
• Use mock/stub only when the user explicitly chooses it, credentials are not available yet, or a real integration would block v1 — document the choice and reason in EVE-BRIEF.md
• Do not commit .env or secrets

5. Monorepo housekeeping (only when applicable)

If the repo already hosts multiple eve agents under a shared parent directory:

1. Update any existing agent index or catalog the repo maintains — for ship-eve, add a row to both agents/README.md and the root README.md with Eve surfaces and Eve capabilities demonstrated (use labels from the capabilities key in agents/README.md)
2. Register the new package in the workspace manifest (pnpm-workspace.yaml, package.json workspaces, etc.)
3. Match package naming and shared config from sibling agents

Skip this step for standalone projects.

6. Verify

pnpm install   # or npm install
pnpm typecheck # if available
pnpm build     # eve build

Tell the user how to run pnpm dev, what to ask in the TUI, and how to exercise the agent over HTTP per the eve docs. Point them to the most-commented files as the learning path. Do not commit unless asked.

---

Examples

User: "I want an agent that summarizes my GitHub PRs"

→ Phase 1 asks: which repo/PR scope? channel? recommended: GitHub connection or API-backed get_pr tool with real token, HTTP channel for v1. Mock only if the user has no credentials yet — note that in the brief.

User: "/create-agent" in a repo that already has eve agents

→ Inventory sibling agents, mirror their layout, interview, brief, scaffold alongside them, update any repo index.

---

Additional resources

• reference.md — EVE-BRIEF template, repo layouts, docs discovery, question bank