Create Agent

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