--- name: create-agent description: Guides a one-question-at-a-time design interview, captures alignment in agent/EVE-BRIEF.md, then scaffolds and implements a runnable eve agent with verbose teaching comments. Use when the user wants to create a new eve agent, build an agent from scratch, or invokes /create-agent. --- # 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](reference.md#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](reference.md#eve-brief-template). - 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](reference.md#docs-discovery). ### 1. Detect project layout Before scaffolding, inspect the repo: | Situation | Action | | ------------------------------ | ------------------------------------------------------------------------------------------------ | | No `agent/` directory anywhere | `npx eve@latest init ` (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](reference.md#repo-layouts). ### 2. Install / scaffold **No eve project yet:** ```bash npx eve@latest init ``` `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:** ```bash cd 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](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 ```bash 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](reference.md) — EVE-BRIEF template, repo layouts, docs discovery, question bank