eve-agentic-app-design

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: eve-agentic-app-design
description: Layer agentic capabilities onto a full-stack Eve app — agents, teams, memory, events, chat, and coordination. Use when designing an app where agents are primary actors, not afterthoughts.
triggers:
  - agentic app design
  - agent architecture
  - design agents
  - agent layer
  - agentic design
  - multi agent
  - agent system design
---

# Agentic App Design on Eve Horizon

Transform a full-stack app into one where agents are primary actors — reasoning, coordinating, remembering, and communicating alongside humans.

## When to Use

Load this skill when:
- Designing an app where agents are primary users alongside (or instead of) humans
- Adding agent capabilities to an existing Eve app
- Choosing between human-first and agent-first architecture
- Deciding how agents should coordinate, remember, and communicate

## Prerequisite: Start with the Foundation

**Load `eve-fullstack-app-design` first.** The agentic layer builds on a solid PaaS foundation. Without a well-designed manifest, service topology, database, pipeline, and deployment strategy, agentic capabilities collapse into chaos.

The progression:
1. **`eve-agent-native-design`** — Principles (parity, granularity, composability, emergent capability)
2. **`eve-fullstack-app-design`** — PaaS foundation (manifest, services, DB, pipelines, deploys)
3. **This skill** — Agentic layer (agents, teams, memory, events, chat, coordination)

Each layer assumes the previous. Skip none.

## Agent Architecture

### Defining Agents

Agents are defined in `agents.yaml` (path set via `x-eve.agents.config_path` in the manifest). Each agent is a persona with a skill, access scope, and policies.

```yaml
version: 1
agents:
  coder:
    slug: coder
    description: "Implements features and fixes bugs"
    skill: eve-orchestration
    harness_profile: primary-coder
    access:
      envs: [staging]
      services: [api, worker]
    policies:
      permission_policy: auto_edit
      git:
        commit: auto
        push: on_success
    gateway:
      policy: routable
```

**Design decisions for each agent:**

| Decision | Options | Guidance |
|----------|---------|----------|
| Slug | Lowercase, alphanumeric + dashes | Org-unique. Used for chat routing: `@eve coder fix the login bug` |
| Skill | Any installed skill name | The agent's core competency. One skill per agent. |
| Harness profile | Named profile from manifest | Decouples agent from specific models. Use profiles, never hardcode harnesses. |
| Gateway policy | `none`, `discoverable`, `routable` | Default to `none`. Make `routable` only for agents that should receive direct chat. |
| Permission policy | `default`, `auto_edit`, `never`, `yolo` | Start with `auto_edit` for worker agents. Use `default` for agents that need human approval. |
| Git policies | `commit`, `push` | `auto` commit + `on_success` push for coding agents. `never` for read-only agents. |

### Designing Teams

Teams are defined in `teams.yaml`. A team groups agents under a lead with a dispatch strategy.

```yaml
version: 1
teams:
  review-council:
    lead: mission-control
    members: [code-reviewer, security-auditor]
    dispatch:
      mode: council
      merge_strategy: majority
  deploy-ops:
    lead: ops-lead
    members: [deploy-agent, monitor-agent]
    dispatch:
      mode: relay
```

**Choose the right dispatch mode:**

| Mode | When to Use | How It Works |
|------|-------------|--------------|
| `fanout` | Independent parallel work | Root job + parallel child per member. Best for decomposable tasks. |
| `council` | Collective judgment | All agents respond, results merged by strategy (majority, unanimous, lead-decides). Best for reviews, audits. |
| `relay` | Sequential handoff | Lead delegates to first member, output passes to next. Best for staged workflows. |

**Design principle**: Most work is `fanout`. Use `council` only when multiple perspectives genuinely improve the outcome. Use `relay` only when each sta