git:20260628.41eace7 to git:20260628.294b019

---

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)

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:

| 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 <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:**

```bash

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](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