eve-agentic-app-design

What this skill does

# 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 stage's output is the next stage's input.

## Harness Profiles

Define named profiles in the manifest. Agents reference profiles, never specific harnesses.

```yaml
x-eve:
  agents:
    profiles:
      primary-coder:
        - harness: claude
          model: opus-4.5
          reasoning_effort: high
        - harness: codex
          model: gpt-5.2-codex
          reasoning_effort: high
      fast-reviewer:
        - harness: mclaude
          model: sonnet-4.5
          reasoning_effort: medium
```

Profile entries are a fallback chain: if the first harness is unavailable, the next is tried. Design profiles around capability needs, not provider loyalty.

### Per-Job Harness Overrides

When the *same* agent must run with different brains per request — e.g., per-user-project model selection, BYOK credentials, or a self-hosted endpoint — pass an inline override at dispatch instead of mutating `agents.yaml` per request:

- Job create: `--harness-override-file <path>` (JSON `{harness, model?, reasoning_effort?, variant?, temperature?}`) and `--env-override KEY=VALUE` (repeatable, supports `${secret.KEY}` interpolation)
- Workflow run/invoke: `--env-override KEY=VALUE` (repeatable)
- API: `harness_profile_override` and `env_overrides` on `CreateJobRequest` and chat dispatch

The orchestrator records `harness_profile_source` (`agent_default`, `string_ref`, `inline_override`, `workflow_template`) plus a stable hash for audit. Reach for overrides only when per-invocation variation is real; otherwise prefer named profiles.

### Model Selection Guidance

| Task Type | Profile Strategy |
|-----------|-----------------|
| Complex coding, architecture | High-reasoning model (opus, gpt-5.2-codex) |
| Code review, documentation | Medium-reasoning model (sonnet, gemini) |
| Triage, routing, classification | Fast model (haiku-equivalent, low reasoning) |
| Specialized domains | Choose the model with strongest domain performance |

## Memory Design

Load `eve-agent-memory` for the full storage primitive catalog. This section focuses on *architectural decisions*.

### What Goes Where

| Information Type | Storage Primitive | Why |
|-----------------|-------------------|-----|
| Scratch notes during a job | Workspace files (`.eve/`) | Ephemeral, dies with the job |
| Job outputs passed to parent | Job attachments | Survives job completion, addressable by job ID |
| Rolling conversation context | Threads | Continuity across sessions, summarizable |
| Curated knowledge | Org Document Store | Versioned, searchable, shared across projects |
| File trees and assets | Org Filesystem (sync) | Bidirectional sync, local editing |
| Structured queries | Managed database | SQL, relationships, RLS |
| Reusable workflows | Skills | Highest-fidelity long-term memory |

### Namespace Conventions

Organize org docs by agent and purpose:

```
/agents/{agent-slug}/learnings/      — discoveries and patterns
/agents/{agent-slug}/decisions/      — decision records
/agents/{agent-slug}/runbooks/       — operational procedures
/agents/shared/                      — cross-agent shared knowledge
/projects/{project-slug}/            — project-scoped knowledge
```

### Lifecycle Strategy

Memory without expiry becomes noise. For every storage location, decide:
1. **Who writes?** Which agents create and update this knowledge.
2. **Who reads?** Which agents query it and when (job start? on demand?).
3. **When does it expire?** Tag with creation dates. Build periodic cleanup jobs.
4. **How does it stay current?** Search before writing. Update beats create.

## Event-Driven Coordination

### The Event Spine

Events are the nervous system of an agentic app. Use them for reactive automation — things that should happen *in response to* other things.

### Trigger Patterns

| Trigger | Event | Response |
|---------|-------|----------|
| Code pushed to main | `github.push` | Run CI pipeline |
| PR opened | `github.pull_request` | Run review council |
| Deploy pipeline failed | `system.pipeline.failed` | Run self-healing workflow |
| Job failed | `system.job.failed` | Run diagnostic agent |
| Job attempt completed | `system.job.attempt.completed` | Run post-session learning workflow (writes back to `user`/`learnings` memory) |
| Org doc created | `system.doc.created` | Notify subscribers, update indexes |
| Scheduled maintenance | `cron.tick` | Run audit, cleanup,