# PROP: Universal Agent Orchestration Layer -- Architecture Research Report

## Source
- **URLs**: Multiple (see per-section citations below)
- **Author**: Researcher agent -- deep research session
- **Date**: 2026-03-04

## Summary

Comprehensive architecture research for iEvo's transformation from a Claude Code-specific agent framework into a universal agent orchestration layer. Covers six research dimensions: native CLI piping, universal agent format, provider routing, pluggable I/O, plugin system design, and desktop wrapper. Each section contains findings on existing tools, gaps, and recommended approach.

---

## 1. Native CLI Passthrough / Transparent Proxy

### What exists today

**PTY-based transparent wrappers:**

| Tool | What it does | GitHub | Notes |
|------|-------------|--------|-------|
| **crai** | Spawns any CLI inside a PTY, bridges stdin/stdout transparently, fires notifications on silence | [turtlekazu/crai](https://github.com/turtlekazu/crai) | Rust, recent (2026). Zero transformation -- colors, spinners, keybindings intact. Echo suppression, typing suppression built in. |
| **CLIProxyAPI** | Wraps Gemini CLI, Codex, Claude Code, Qwen Code as OpenAI-compatible API endpoints | [router-for-me/CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) | Node.js. OAuth auth for all providers. Homebrew formula exists. |
| **ProxyPilot** | Windows-native CLIProxyAPI fork with TUI, system tray, multi-provider OAuth | [Finesssee/ProxyPilot](https://github.com/Finesssee/ProxyPilot) | Desktop-native variant |
| **ProxyPal** | Desktop app wrapping CLIProxyAPI with clean UI for connection management | [heyhuynhgiabuu/proxypal](https://github.com/heyhuynhgiabuu/proxypal) | Desktop variant |

**Python PTY libraries:**

| Library | Purpose | Status |
|---------|---------|--------|
| **pexpect** | Spawn child process in PTY, control interactively | Mature, 2.5k+ stars |
| **ptyprocess** | Low-level PTY wrapper (used by pexpect) | Stable |
| Python `pty` stdlib | Basic PTY support (openpty, fork, spawn) | Built-in |

**Key patterns observed:**

1. **crai pattern**: `openpty()` -> fork child process -> bridge raw stdin/stdout with zero transformation -> monitor output stream for events. This is the exact pattern iEvo needs for transparent CLI passthrough.

2. **CLIProxyAPI pattern**: Spawn CLI with piped stdio -> parse responses -> expose as API. This is the "CLI as API" pattern -- useful for programmatic access but loses interactive features (TUI, keybindings).

### What's missing

No existing tool combines:
- Transparent PTY passthrough (preserving full interactive experience)
- Event interception (hook into tool calls, inject context)
- Multi-CLI support (switch between Claude Code, Codex, Ollama in one session)
- Structured metadata extraction (parse tool calls from the stream)

### Recommended approach for iEvo

**Phase 1 -- PTY passthrough layer:**
- Use Python's `pty` module or `pexpect` to spawn the target CLI (Claude Code, Codex) inside a pseudo-terminal
- Bridge raw stdin/stdout transparently -- user sees the exact same experience as running the CLI directly
- Add event detection layer: monitor output for patterns (tool calls, thinking blocks, errors) without modifying them
- This gives iEvo a "transparent proxy" that preserves 100% of native CLI features

**Phase 2 -- Event hooks:**
- Parse structured output (Claude Code's hook system already emits JSON events)
- Claude Code hooks (PreToolUse, PostToolUse, Stop) can be configured via `.claude/settings.json` -- iEvo writes these configs, the CLI executes them natively
- For Codex: similar approach via `config.toml` agent configuration

**Phase 3 -- Multi-CLI router:**
- Based on agent definition, spawn the correct CLI
- Same PTY bridge, different underlying process

---

## 2. Universal Agent Format / Transpiler Pattern

### What exists today

**Claude Code agent format** (source: [code.claude.com/docs/en/sub-agents](https://code.claude.com/docs/en/sub-agents)):
```yaml
---
name: code-reviewer
description: Reviews code for quality
tools: Read, Glob, Grep
disallowedTools: Write, Edit
model: sonnet              # sonnet | opus | haiku | inherit
permissionMode: default    # default | acceptEdits | dontAsk | bypassPermissions | plan
maxTurns: 50
memory: user               # user | project | local
background: false
isolation: worktree
skills:
  - api-conventions
mcpServers:
  - slack
hooks:
  PreToolUse: [...]
  PostToolUse: [...]
---
System prompt in Markdown...
```

**OpenAI Codex agent format** (source: [developers.openai.com/codex/config-reference](https://developers.openai.com/codex/config-reference)):
```toml
[agents.reviewer]
description = "Find security, correctness, and test risks in code."
config_file = "./agents/reviewer.toml"

# In reviewer.toml:
model = "o3"
model_reasoning_effort = "high"    # minimal | low | medium | high | xhigh
sandbox_mode = "read-only"         # read-only | workspace-write | danger-full-access
developer_instructions = "Focus on security..."
approval_policy = "unless-allow-listed"
```

Plus `AGENTS.md` (per-directory instructions, like CLAUDE.md but standardized).

**AGENTS.md standard** (source: [agents.md](https://agents.md/)):
- Open format adopted by 60k+ projects
- Supported by: Claude Code, Codex, Copilot, Cursor, VS Code, Devin, Gemini CLI
- Now under Agentic AI Foundation (Linux Foundation)
- Complementary to agent configs -- provides project-level context, not agent definitions

**Existing "transpiler" analogs:**

| Pattern | What it does | Relevance |
|---------|-------------|-----------|
| **Kompose** ([kubernetes/kompose](https://github.com/kubernetes/kompose)) | Docker Compose -> Kubernetes manifests | Direct analog: one format -> multiple deployment targets. 10k+ stars. |
| **Fabric patterns** ([danielmiessler/Fabric](https://github.com/danielmiessler/Fabric)) | Markdown prompt templates, piped via CLI to any LLM provider | Agent format is just Markdown with system prompts. Provider-agnostic. 300+ patterns. |
| **LangChain** | Unified Python interface across providers | Abstracts at API level, not at config file level |

**No existing "agent config transpiler"** -- nobody has built a tool that takes a universal agent definition and compiles it to Claude Code .md + Codex .toml + other formats.

### Field mapping analysis

| Concept | Claude Code (YAML frontmatter) | Codex (TOML) | Notes |
|---------|-------------------------------|--------------|-------|
| Name | `name` | Table key `[agents.NAME]` | Direct mapping |
| Description | `description` | `description` | Direct mapping |
| Model | `model` (sonnet/opus/haiku/inherit) | `model` (o3/o4-mini/etc) | Provider-specific model names |
| System prompt | Markdown body | `developer_instructions` or separate AGENTS.md | Different mechanisms |
| Tool restrictions | `tools`, `disallowedTools` | N/A (sandbox_mode instead) | Fundamentally different |
| Sandbox | N/A (permission modes) | `sandbox_mode` | Conceptually similar, different granularity |
| Reasoning effort | N/A | `model_reasoning_effort` | Codex-specific |
| Memory | `memory: user/project/local` | N/A | Claude Code-specific |
| Hooks | `hooks: {PreToolUse: [...]}` | N/A | Claude Code-specific |
| Skills | `skills: [...]` | N/A | Claude Code-specific |
| Max turns | `maxTurns` | N/A | Claude Code-specific |
| Concurrency | N/A | `max_threads`, `max_depth` | Codex-specific |
| Timeout | N/A | `job_max_runtime_seconds` | Codex-specific |

### Key insight

The two formats are NOT simply different serializations of the same data. They reflect fundamentally different architectures:
- Claude Code: rich subagent system with hooks, skills, memory, tool-level permissions
- Codex: simpler role-based delegation with sandbox isolation and reasoning effort controls

A "transpiler" cannot be a 1:1 mapping. It must be a **semantic adapter** -- understanding intent and mapping to the closest equivalent in each target.

### Recommended approach for iEvo

**iEvo Universal Agent Format (UAF):**

```yaml
---
# Core (universal)
name: code-reviewer
description: Reviews code for quality and best practices
model: fast              # abstract tier: fast | standard | powerful | reasoning
prompt_file: null        # optional external prompt file

# Capability (semantic, mapped per-provider)
capabilities:
  tools: [read, search, shell]    # abstract tool names
  sandbox: read-only              # none | read-only | workspace | full
  max_turns: 50
  reasoning_effort: medium        # low | medium | high (mapped to Codex reasoning_effort, Claude model selection)

# Provider-specific overrides (optional)
providers:
  claude:
    model: sonnet
    memory: user
    skills: [api-conventions]
    hooks:
      PreToolUse: [...]
  codex:
    model: o4-mini
    model_reasoning_effort: medium
    sandbox_mode: read-only
  ollama:
    model: llama3.3

# iEvo-specific
evolution:
  memory: user
  overlay: .ievo/evolution/code-reviewer.md
---

System prompt in Markdown (shared across all providers)...
```

**Transpiler design:**
1. Read UAF
2. For Claude Code: generate `.claude/agents/<name>.md` with YAML frontmatter + mapped fields
3. For Codex: generate `.codex/config.toml` `[agents.NAME]` section + `AGENTS.md` for instructions
4. For Ollama: generate API call config with system prompt
5. Provider-specific overrides take precedence over abstract mappings

**Abstract model tiers -> concrete models:**

| Tier | Claude | Codex | Ollama |
|------|--------|-------|--------|
| fast | haiku | o4-mini | llama3.2:3b |
| standard | sonnet | o3 | llama3.3 |
| powerful | opus | o3 (xhigh) | deepseek-r1 |
| reasoning | opus + extended thinking | o3 (xhigh reasoning) | deepseek-r1 |

---

## 3. Provider Routing

### What exists today

| Tool | Stars | Approach | Providers | Language |
|------|-------|----------|-----------|----------|
| **LiteLLM** ([BerriAI/litellm](https://github.com/BerriAI/litellm)) | 20k+ | Proxy server + SDK, OpenAI-compatible API | 100+ (OpenAI, Anthropic, Ollama, Bedrock, etc.) | Python |
| **RouteLLM** ([lm-sys/RouteLLM](https://github.com/lm-sys/RouteLLM)) | 4k+ | Learned router (ML classifier), cost-quality tradeoff | Via LiteLLM | Python |
| **Not Diamond** ([notdiamond.ai](https://www.notdiamond.ai/)) | N/A (SaaS) | Meta-model routing, per-query optimal model selection | All major providers | API |
| **OpenRouter** ([openrouter.ai](https://openrouter.ai/)) | N/A (SaaS) | Auto-router powered by NotDiamond | All major providers | API |
| **Vercel AI SDK** ([vercel/ai](https://github.com/vercel/ai)) | 15k+ | Unified TypeScript interface, provider-agnostic | 25+ providers | TypeScript |
| **Microsoft BEST-Route-LLM** ([microsoft/best-route-llm](https://github.com/microsoft/best-route-llm)) | New | Multi-sampling routing, cost-quality optimization | Multiple | Python |
| **NVIDIA LLM Router** ([NVIDIA-AI-Blueprints/llm-router](https://github.com/NVIDIA-AI-Blueprints/llm-router)) | New | Enterprise routing blueprint | Multiple | Python |
| **Aider architect mode** ([Aider-AI/aider](https://github.com/Aider-AI/aider)) | 30k+ | Dual-model: Architect (expensive) + Editor (cheap) | All via LiteLLM | Python |

### Key routing patterns

1. **Cost-based**: Route cheap queries to small models, expensive queries to large models (RouteLLM -- 85% cost reduction, 95% GPT-4 quality)
2. **Capability-based**: Route based on task type (coding -> Codex/Claude, simple queries -> Ollama)
3. **Role-based**: Different pipeline stages use different models (Aider architect pattern)
4. **Fallback chains**: Primary -> secondary -> tertiary (LiteLLM built-in)

### What's missing for iEvo

Existing routers operate at the **API level** -- they route API calls to different model endpoints. iEvo needs routing at the **CLI level** -- different agents need to run inside different CLI tools (Claude Code CLI, Codex CLI, Ollama CLI), not just different API endpoints.

The gap: no router exists that says "this agent should run as a Claude Code subagent" vs "this agent should run as a Codex agent" vs "this agent should use Ollama via API."

### Recommended approach for iEvo

**Two-layer routing:**

Layer 1 -- **Provider selection** (static, per-agent):
- Defined in agent UAF: `model: standard` -> resolves to a specific provider + model
- Default provider set in iEvo config
- Override per-agent via `providers:` section

Layer 2 -- **Runtime optimization** (dynamic, optional):
- Use LiteLLM as the unified API gateway for API-based agents (Ollama, direct API calls)
- For CLI-based agents (Claude Code, Codex), route to the correct CLI via PTY layer
- Cost tracking via LiteLLM's built-in cost tracking

**For MVP: static routing only.** Dynamic cost-based routing is Phase 3.

---

## 4. Pluggable I/O / Multi-Channel Architecture

### What exists today

| Tool | Channels | Architecture | Stars | Language |
|------|----------|-------------|-------|----------|
| **OpenClaw** ([openclaw/openclaw](https://github.com/openclaw/openclaw)) | WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Web | Channel Layer adapter pattern. Single Node.js process, multi-channel gateway | 100k+ | TypeScript |
| **Langclaw** ([tisu19021997/langclaw](https://github.com/tisu19021997/langclaw)) | Telegram, Discord, WebSocket | `app.add_channel()` pattern. Built on LangChain/LangGraph | New | Python |
| **Botpress** ([botpress.com](https://botpress.com)) | WhatsApp, Slack, Messenger, Web, SMS, etc. | Visual builder + channel connectors | 14k+ | TypeScript |
| **Rasa** ([RasaHQ/rasa](https://github.com/RasaHQ/rasa)) | Web, Audio, Messaging (via API integrations) | NLU pipeline + channel API | 19k+ | Python |
| **Vercel Chat SDK** | Telegram, Slack, Discord, GitHub, Teams, Web | Adapter pattern per channel | Part of AI SDK | TypeScript |

### Channel adapter pattern (from OpenClaw)

```
Platform Connectors (WhatsApp, Telegram, Discord, ...)
    |
    v
Channel Layer (adapts platform messages -> common internal structure)
    |
    v
Agent Core (processes messages, generates responses)
    |
    v
Channel Layer (adapts responses -> platform-specific format)
    |
    v
Platform Connectors (send responses)
```

Key insight from OpenClaw: the agent core never sees platform-specific code. The Channel Layer handles all translation.

### Recommended approach for iEvo

**Interface abstraction:**

```
iEvo Core (agent orchestration, provider routing, pipeline)
    |
    v
I/O Adapter Protocol (Python abstract base class / Protocol)
    |
    +--- TUI Adapter (Textual -- current)
    +--- CLI Adapter (raw stdin/stdout -- headless mode)
    +--- Telegram Adapter
    +--- Discord Adapter
    +--- Web Adapter (WebSocket)
    +--- Desktop Adapter (Tauri IPC)
```

**Core messages (universal format):**
```python
@dataclass
class UserMessage:
    text: str
    channel: str           # "tui" | "telegram" | "discord" | "web" | ...
    user_id: str
    session_id: str
    attachments: list[Attachment] = field(default_factory=list)

@dataclass
class AgentResponse:
    text: str
    structured: dict | None = None    # for rich responses
    actions: list[Action] = field(default_factory=list)  # buttons, forms
```

**Structured interview model (Apple UX):**
Each pipeline stage (requirements gathering, specification, planning) is a structured conversation flow with defined questions, validation, and transitions. This model is channel-independent -- same flow on Telegram and TUI.

**For MVP: keep TUI + add CLI headless adapter for CI/automation.** Telegram/Discord are Phase 2.

---

## 5. Plugin System Design

### What exists today

| System | Plugin mechanism | Key features |
|--------|-----------------|-------------|
| **Claude Code plugins** ([code.claude.com/docs/en/plugins](https://code.claude.com/docs/en/plugins)) | Bundles: slash commands, subagents, MCP servers, hooks, skills | Full lifecycle integration. 9,000+ extensions as of 2026. |
| **VS Code extensions** | Extension API, contribution points, activation events | Most successful plugin ecosystem in dev tools. Language Server Protocol for language features. |
| **MCP (Model Context Protocol)** ([modelcontextprotocol.io](https://modelcontextprotocol.io)) | JSON-RPC 2.0, tool/resource/prompt registration | Universal standard. 10,000+ servers. Adopted by Claude, ChatGPT, Codex, Copilot, VS Code. |
| **Fabric** | Markdown "patterns" (prompt templates) in `~/.config/fabric/patterns/` | Simple, file-based. 300+ community patterns. |
| **AGENTS.md** ([agents.md](https://agents.md/)) | Per-directory Markdown instructions, no structure required | 60k+ projects. Agentic AI Foundation. |

### Key lessons from successful plugin systems

1. **MCP is the de facto standard for tool integration** -- don't build a competing protocol
2. **Claude Code plugins show the right granularity**: agents + slash commands + hooks + MCP servers in one package
3. **VS Code teaches: contribution points** -- explicit extension points where plugins can inject behavior
4. **Fabric teaches: simplicity** -- a plugin can be just a Markdown file

### Recommended approach for iEvo

**iEvo Plugin structure:**
```
plugins/
  my-plugin/
    plugin.yaml          # Metadata: name, version, description, author
    agents/              # Agent definitions (UAF format)
      my-agent.md
    adapters/            # I/O channel adapters
      telegram.py
    providers/           # LLM provider integrations
      custom-llm.py
    skills/              # Slash command skills
      my-skill.md
    hooks/               # Lifecycle hooks
      pre-run.py
    mcp/                 # MCP server configs
      my-server.json
```

**Plugin types (contribution points):**
1. **Provider plugins**: Add new LLM providers (e.g., Ollama, Groq, local models)
2. **Adapter plugins**: Add new I/O channels (Telegram, Discord, Web)
3. **Agent plugins**: Add new agent definitions (UAF format)
4. **Skill plugins**: Add new slash commands / workflows
5. **Hook plugins**: Add lifecycle event handlers

**Plugin API contract:**
- Each plugin type has a Python Protocol (interface)
- Plugins register via `plugin.yaml` -- iEvo discovers them at startup
- No direct function imports -- plugins communicate via well-defined messages
- Versioned API contract -- plugins declare minimum iEvo version

**For MVP: provider plugins + agent plugins.** Adapter and hook plugins are Phase 2.

---

## 6. Desktop Wrapper (Tauri)

### What exists today

**Terminal-in-Tauri projects:**

| Project | What it does | Notes |
|---------|-------------|-------|
| **tauri-plugin-pty** ([Tnze/tauri-plugin-pty](https://github.com/Tnze/tauri-plugin-pty)) | Tauri v2 plugin: embed terminal with xterm.js + PTY | Latest release: v0.1.1 (2025-08-22). Low adoption (137 npm weekly downloads). |
| **tauri-terminal** ([marc2332/tauri-terminal](https://github.com/marc2332/tauri-terminal)) | Demo terminal emulator built with Tauri | Proof of concept |

**Python in Tauri:**

| Approach | How it works | Complexity |
|----------|-------------|------------|
| **Sidecar** (recommended) | Bundle Python CLI as executable via PyInstaller/PyOxidizer. Tauri launches it as external binary. | Medium. Increases bundle size. |
| **tauri-plugin-python** ([marcomq/tauri-plugin-python](https://github.com/marcomq/tauri-plugin-python)) | Run Python code in Rust backend via PyO3 or RustPython | High complexity. Limited Python ecosystem access. |
| **Local API server** | Python runs as localhost HTTP/WebSocket server, Tauri frontend connects to it | Medium. Clean separation. |

**Reference implementations (Rust terminals):**

| Terminal | Stars | Stack | Notes |
|---------|-------|-------|-------|
| **Warp** ([warp.dev](https://www.warp.dev)) | N/A (proprietary) | Rust + custom renderer (Metal/OpenGL) | AI-native terminal. Not using Tauri. |
| **Alacritty** ([alacritty/alacritty](https://github.com/alacritty/alacritty)) | 60k+ | Rust + OpenGL | Fast, minimal. No tabs/splits. |
| **Ghostty** | 20k+ | Zig (not Rust) + Metal/OpenGL | Modern, fast, feature-rich |
| **Rio** ([raphamorim/rio](https://github.com/raphamorim/rio)) | 4k+ | Rust + WGPU | Desktop + browser target |

### Tauri vs Electron

| Dimension | Tauri | Electron |
|-----------|-------|----------|
| Binary size | 2-5 MB | 100-150 MB |
| Memory usage | Low (system webview) | High (bundled Chromium) |
| Language | Rust backend, web frontend | JavaScript/TypeScript |
| Python integration | Sidecar or plugin | Child process |
| PTY support | Via plugin (tauri-plugin-pty) | Via node-pty (mature, well-tested) |
| Maturity | v2 (stable) | Very mature |
| Community | Growing rapidly | Massive |

### Recommended approach for iEvo

**Architecture:**
```
Tauri shell (Rust)
  +--- xterm.js terminal widget (renders PTY output)
  +--- Custom UI panels (agent status, pipeline view, file tree)
  +--- IPC bridge to Python backend
       |
       v
iEvo Python backend (runs as sidecar or local server)
  +--- Agent orchestration
  +--- PTY management (spawn Claude Code / Codex inside PTY)
  +--- Provider routing
  +--- Plugin system
```

**Recommended stack:**
- **Tauri v2** for the desktop shell (small binary, Rust performance)
- **xterm.js** for the terminal rendering (proven, used by VS Code terminal)
- **tauri-plugin-pty** for PTY management
- **Python backend as sidecar** (bundled via PyInstaller) or **local WebSocket server**
- **React/Svelte/Vue** for the non-terminal UI panels

**For MVP: keep the Textual TUI as primary.** Desktop wrapper is Phase 3. When building it, use Tauri + xterm.js + Python sidecar (local WebSocket server pattern for cleanest separation).

---

## Overall Architecture Recommendation

### Target architecture

```
+----------------------------------------------------------+
|                    iEvo Universal Shell                    |
|  (Tauri desktop OR Textual TUI OR Telegram/Discord/Web)  |
+----------------------------------------------------------+
                          |
                    I/O Adapter Protocol
                          |
+----------------------------------------------------------+
|                     iEvo Core                             |
|  +--------------------------------------------------+    |
|  |  Agent Manager                                    |    |
|  |  - Reads Universal Agent Format (UAF)             |    |
|  |  - Transpiles to provider-specific configs        |    |
|  |  - Manages agent lifecycle                        |    |
|  +--------------------------------------------------+    |
|  |  Provider Router                                  |    |
|  |  - Static routing (per-agent provider assignment) |    |
|  |  - CLI spawner (PTY for Claude Code / Codex)      |    |
|  |  - API caller (LiteLLM for Ollama / direct API)   |    |
|  +--------------------------------------------------+    |
|  |  Pipeline Engine                                  |    |
|  |  - SDD pipeline (spec -> plan -> code -> test)    |    |
|  |  - Structured interview flows                     |    |
|  |  - Evolution tracking                             |    |
|  +--------------------------------------------------+    |
|  |  Plugin System                                    |    |
|  |  - Providers, adapters, agents, skills, hooks     |    |
|  +--------------------------------------------------+    |
+----------------------------------------------------------+
                          |
            +-------------+-------------+
            |             |             |
     Claude Code     Codex CLI      LiteLLM
     (via PTY)       (via PTY)     (Ollama, API)
```

### MVP vs Phase 2 vs Phase 3

**MVP (Phase 1) -- "One format, two providers":**
1. Universal Agent Format (UAF) -- `.md` with extended YAML frontmatter
2. UAF -> Claude Code transpiler (generate `.claude/agents/*.md`)
3. UAF -> Codex transpiler (generate `.codex/config.toml` + `AGENTS.md`)
4. Static provider routing (agent config says which provider)
5. PTY passthrough for Claude Code CLI (transparent proxy)
6. Keep Textual TUI as primary interface
7. Plugin skeleton (provider plugins only)

Effort: Medium (4-6 weeks)
Impact: Users write agents once, deploy to Claude Code or Codex

**Phase 2 -- "Multi-channel + Ollama":**
1. PTY passthrough for Codex CLI
2. LiteLLM integration for Ollama and direct API calls
3. Telegram adapter (I/O plugin)
4. Discord adapter (I/O plugin)
5. Structured interview mode (channel-independent conversation flows)
6. Adapter plugin API
7. Agent + skill plugin API

Effort: High (6-10 weeks)
Impact: Same agents work on Telegram, Discord, and CLI. Cheap tasks route to Ollama.

**Phase 3 -- "Desktop + dynamic routing":**
1. Tauri desktop wrapper (xterm.js + custom panels)
2. Dynamic provider routing (cost-based, capability-based)
3. Web interface adapter (WebSocket)
4. Full plugin marketplace
5. Agent team orchestration across providers

Effort: High (8-12 weeks)
Impact: Full desktop experience, automatic cost optimization

### What to build custom vs use off-the-shelf

| Component | Build or Buy | Recommendation |
|-----------|-------------|----------------|
| Universal Agent Format | Build | No existing standard covers iEvo's needs. AGENTS.md is too simple (no agent config). Claude/Codex formats are provider-locked. |
| UAF Transpiler | Build | No existing tool. Core IP of iEvo. |
| PTY passthrough | Build (thin layer) | Use Python `pty`/`pexpect` for the low-level PTY. Build the transparent bridge + event detection. ~200 lines of core code. |
| Provider routing (API) | Use LiteLLM | 20k+ stars, 100+ providers, Python, MIT. No reason to build custom. |
| Provider routing (CLI) | Build | No existing tool routes to CLI tools. Build a thin dispatcher. |
| I/O adapter protocol | Build | Define the Protocol. Adapters are plugins. |
| TUI | Keep Textual | Already built. Works well. |
| Telegram/Discord adapters | Build (using libraries) | Use `python-telegram-bot` + `discord.py`. Write thin adapter. |
| Desktop shell | Use Tauri | Don't build a terminal emulator from scratch. Use Tauri + xterm.js + tauri-plugin-pty. |
| Plugin system | Build | Define plugin types, discovery, API contracts. ~500 lines of core framework. |
| MCP integration | Use MCP | Standard protocol. Use `modelcontextprotocol` Python SDK. |

### Apple UX principle implementation

"Works out of the box" means:
1. `ievo` starts the TUI
2. User picks a provider (or it auto-detects: Claude Code installed? Use that. Codex installed? Use that. Neither? Offer Ollama.)
3. Pre-built agent team loads (spec-writer, architect, coder -- already in iEvo marketplace)
4. User describes what they want
5. Pipeline runs automatically: spec -> plan -> code -> test
6. No configuration required beyond provider selection

---

## Scores

- Applicability: 5/5 (this IS the next evolution of iEvo)
- Effort: high (full architecture, phased delivery)
- Impact: quality, speed, reliability, UX (all dimensions)

## Affected Components

- `src/ievo/core/` -- new modules: `provider.py`, `transpiler.py`, `pty_bridge.py`, `router.py`
- `src/ievo/plugins/` -- new package: plugin discovery, loading, API
- `src/ievo/adapters/` -- new package: I/O adapter protocol and implementations
- `src/ievo/marketplace/agents/*.md` -- migrate to UAF format
- `src/ievo/tui/app.py` -- refactor to use I/O adapter protocol
- `src/ievo/core/config.py` -- provider configuration
- New repo or package: `ievo-tauri` -- desktop shell (Phase 3)
