# PROP: Universal Agent Format (UAF) and Transpiler

## Source
- **URL**: https://code.claude.com/docs/en/sub-agents (Claude Code format), https://developers.openai.com/codex/config-reference/ (Codex format), https://agents.md/ (AGENTS.md standard), https://github.com/kubernetes/kompose (transpiler pattern)
- **Author**: Anthropic (Claude Code), OpenAI (Codex), AAIF (AGENTS.md), Kubernetes (Kompose)
- **Date**: 2025-2026

## Summary
Define a Universal Agent Format (UAF) that extends iEvo's current .md-with-YAML-frontmatter format to include abstract capability declarations and optional provider-specific overrides. Build a transpiler that compiles UAF into Claude Code subagent .md files, Codex config.toml sections, and Ollama API configurations. This follows the Kompose pattern (Docker Compose -> Kubernetes) applied to AI agent configs.

## Relevance to iEvo
iEvo already has the right foundation: agents are .md files with YAML frontmatter, deployed to `.claude/agents/`. The current format is Claude Code-specific. Extending it to a universal format (with Claude Code as one compilation target) positions iEvo as the "write once, deploy anywhere" agent framework. IDEA-012 (Codex format) becomes a concrete implementation path.

## Proposed Change

### 1. UAF specification
Extend the current frontmatter with:
- **Abstract model tiers**: `model: fast|standard|powerful|reasoning` (mapped to concrete models per provider)
- **Abstract capabilities**: `capabilities.tools: [read, search, shell, write]` (mapped to provider tool names)
- **Abstract sandbox**: `capabilities.sandbox: none|read-only|workspace|full`
- **Provider overrides**: `providers.claude: {...}`, `providers.codex: {...}`, `providers.ollama: {...}`
- The Markdown body remains the universal system prompt

### 2. Transpiler module
Create `src/ievo/core/transpiler.py` with:
- `transpile_to_claude(agent: UAFAgent) -> str` -- generates `.claude/agents/<name>.md`
- `transpile_to_codex(agent: UAFAgent) -> str` -- generates TOML config section + AGENTS.md instructions
- `transpile_to_ollama(agent: UAFAgent) -> dict` -- generates API call configuration
- Each transpiler handles the semantic mapping (abstract tools -> provider tools, abstract model -> concrete model)

### 3. Model tier mapping (configurable)
Default mapping stored in `~/.ievo/config.json` or `.ievo/manifest.yaml`, user-overridable:
```yaml
model_map:
  fast: {claude: haiku, codex: o4-mini, ollama: "llama3.2:3b"}
  standard: {claude: sonnet, codex: o3, ollama: llama3.3}
  powerful: {claude: opus, codex: o3, ollama: deepseek-r1}
  reasoning: {claude: opus, codex: o3, ollama: deepseek-r1}
```

### 4. Migration path
Existing iEvo agents (current Claude-only format) remain valid UAF -- the transpiler treats a .md with only Claude Code fields as a UAF that targets Claude only. No breaking changes.

## Affected Components
- New: `src/ievo/core/transpiler.py` (transpiler engine)
- New: `src/ievo/core/uaf.py` (UAF model and parser, extends current agent.py)
- Modified: `src/ievo/marketplace/agents/*.md` (add abstract tiers, keep backward-compat)
- Modified: `src/ievo/core/config.py` (model tier mapping configuration)
- Modified: `src/ievo/commands/init.py` (generate provider-specific configs during init)
- New: `src/ievo/core/codex.py` (Codex-specific config generation)

## Scores
- Applicability: 5/5
- Effort: medium (format design is careful work; transpiler per target is straightforward)
- Impact: UX (write agents once), speed (no manual format conversion)
