# Project Context

<!-- Updated by Spec Writer agent at the end of each session -->

## Project Name
ievo-cli — Interactive console tool for the iEvo self-evolving AI agent framework

## Project Description
The CLI is the primary interface for the iEvo ecosystem. It provides both a Textual TUI dashboard and traditional CLI commands for project initialization, agent management, pipeline orchestration, and evolution tracking. The CLI launches Docker sandboxes for agent execution while preserving full native Claude Code access.

## Tech Stack
- Python 3.13+ (CLI, TUI, orchestration)
- Typer (CLI framework) + Rich (terminal formatting) + Textual (TUI dashboard)
- uv (package manager) + hatchling (build system)
- Docker (agent execution sandbox — `ievoai/sandbox:latest`)
- Claude Code CLI (`claude -p`) for agent sessions
- OAuth token (`CLAUDE_CODE_OAUTH_TOKEN`) for subscription-based auth
- pytest + ruff (testing + linting)

## Current State
- Total requirements: 13 (REQ-000 through REQ-012)
- Implemented: 4 (REQ-000 through REQ-003)
- Review: 2 (REQ-007 — TUI integration tests; REQ-008 — agent version check)
- Ready: 7 (REQ-004 — CLI self-update; REQ-005 — startup version check; REQ-006 — bundle marketplace; REQ-009 — template version tracking; REQ-010 — kernel evolution + CLAUDE.md patch + uninstall; REQ-012 — debug capture trajectory logging)
- Draft: 1 (REQ-011 — skills install/uninstall)
- Planned: 7 (PLAN-REQ-004, PLAN-REQ-005, PLAN-REQ-006, PLAN-REQ-007, PLAN-REQ-008, PLAN-REQ-009, PLAN-REQ-010 all approved)
- In progress: 0
- Blocked: 0
- Change Requests: 1 (CR-001 ready — repurposes ievo update command, affects REQ-002)
- CLI model: TUI-first. `ievo` (no args) → TUI dashboard (auto-init with confirmation if no project)
- Active CLI commands: `ievo` (TUI), `ievo config`, `ievo update`, `ievo uninstall` (REQ-010 adds uninstall)
- Deprecated CLI commands: init, add, remove, list, run, team, orchestrate, learn, deps, dev
- Note: `update` was deprecated (pointing to HR agent) but is being repurposed by REQ-004 as a first-class self-update command. After REQ-004 is implemented it will no longer carry a deprecation warning.
- Deprecation utility: `src/ievo/utils/deprecation.py` — `deprecated_command(name, alternative=None)`
- `add` split: `add_agents()` = internal API (no warning), `add()` = CLI wrapper (with warning)
- TUI dashboard: Textual app with agents table, pipeline view (`src/ievo/tui/app.py`)
- Docker sandbox: working (`ievoai/sandbox:latest`)
- Tests: full test suite with pytest, 100% coverage requirement

## Key Entities / Components
- **CLI entry point**: `src/ievo/cli.py` — Typer app, registers all commands
- **Commands**: `src/ievo/commands/` — init, add, remove, update, list, run, team, learn, dev
- **Core**: `src/ievo/core/` — config, project, agent, docker, registry
- **TUI**: `src/ievo/tui/app.py` — Textual dashboard (agents, pipeline, evolution, files)
- **Docker sandbox**: `ievoai/sandbox:latest` — isolated agent execution
- **Marketplace**: `ievo-ai/marketplace` — agent registry (9 agents)
- **Global config**: `~/.ievo/config.json` — user preferences, auth, telemetry

## Architecture Notes
- Interactive model: `ievo` without args → TUI dashboard, `ievo <cmd>` → CLI
- Preserve full native Claude Code access + add orchestration on top
- Docker sandbox starts interactively when Claude is needed
- Session ID for continuity (`--resume`)
- `.claude/` mounted for session persistence + hooks
- Marketplace registry cached in `~/.ievo/cache/registry.yaml`

## Architecture Vision (2026-03-04 research)
- **Universal Agent Format (UAF)**: extend current .md frontmatter with abstract model tiers, capabilities, provider overrides. Transpile to Claude Code .md / Codex .toml / Ollama API configs.
- **Native CLI passthrough**: PTY bridge (pexpect/pty) for transparent proxy of Claude Code / Codex CLIs. Zero transformation of stdio.
- **Provider routing**: static (per-agent) + LiteLLM (API gateway for 100+ providers). CLI providers via PTY, API providers via LiteLLM.
- **Pluggable I/O**: IOAdapter Protocol — TUI, CLI headless, Telegram, Discord, Web, Desktop (Tauri).
- **Plugin system**: 5 contribution points (providers, adapters, agents, skills, hooks). File-based discovery via plugin.yaml.
- **Desktop wrapper (Phase 3)**: Tauri v2 + xterm.js + tauri-plugin-pty + Python sidecar/WebSocket.
- **Key finding**: no existing "agent config transpiler" exists — UAF + transpiler is greenfield and core IP.
- **Key tools**: LiteLLM (20k stars), RouteLLM (ICLR 2025), OpenClaw (100k stars, channel pattern), crai (PTY pattern), tauri-plugin-pty.
- Proposals: 7 files in .ievo/backlog/PROP-2026-03-04-*

## Known Patterns / Risks
- **Pipeline skip risk (2026-03-03)**: Agents and general assistants tend to skip spec-writer when user phrasing feels like a direct coding request ("let's add X"). The coder's existing "never implement without REQ" rule is present but not enforced as a hard pre-flight gate. Evolution signal filed: https://github.com/ievo-ai/curator/issues/1
- **Git flow assumption risk (2026-03-03)**: Agents commit directly to the current branch when git workflow conventions are not in memory, instead of asking the user first. The coder has a branch naming convention (`feat/REQ-xxx-<desc>`) but no pre-flight gate that checks: "do I know this project's git flow?" before the first commit of a new requirement. Evolution signal filed: see DECISIONS.md D-012. User's actual git flow: trunk-based development — short-lived feature branches off `main`, fast PRs to `main`. Branch naming: `<type>/<ticket>-<description>` (e.g., `feat/REQ-001-auto-init-confirmation`).
- **Mock-over-state risk (2026-03-03)**: When a CI failure is caused by a function that reads stdin, the coder defaults to mocking that function rather than finding and satisfying the guard condition that prevents it from being called. The correct fix is always: identify the guard, write real config state, verify the guard naturally skips the prompt. Function mocks on application logic hide real code paths and silently pass after import renames. Evolution signal filed: https://github.com/ievo-ai/curator/issues/3
- **Information disclosure risk (2026-03-03)**: The evolution agent posted internal structural details to a public repository. The existing sanitization rule covered credentials only. All agents posting to external/public repos must apply the blog-post test: strip config key names, code snippets, file structure details, and naming conventions before posting. Describe error classes and proposed fixes in terms of behaviour patterns only. Decision recorded in D-014. Evolution signal filed: https://github.com/ievo-ai/curator/issues/4
- **Documentation gap risk (2026-03-03)**: Coder committed new public functions, classes, and enums without meaningful docstrings. The acceptance self-review checklist covered tests and coverage but not code-level documentation. User had to ask explicitly before a fix was made. Rule added to CLAUDE.md "Acceptance before done" checklist. Evolution signal filed: https://github.com/ievo-ai/curator/issues/7
- **Dual-check inconsistency risk (2026-03-03)**: Two functions checking the same logical condition ("is the project initialized?") used different physical predicates — one checked for a directory, the other for a manifest file. This created a deadlock: the detector offered to initialize, the init command refused because the directory already existed. Root cause: Architect plan did not define a single canonical predicate. Test for the guard was isolated and missed the full trigger chain. Rules added to CLAUDE.md: single canonical predicate + integration tests for guard chains. Evolution signal filed: https://github.com/ievo-ai/curator/issues/8
- **Mock-only TUI test gap risk (2026-03-03)**: TUI launched with focus on the wrong widget (internal tab strip instead of primary interactive widget). All mock-based TUI tests passed — focus, post-mount widget state, and keyboard routing are invisible to tests that never mount the real application. Root cause: TUI testing rule did not enumerate focus, navigation, and primary interaction as explicit required coverage areas. Rule strengthened in CLAUDE.md to require Pilot tests covering (1) initial focus, (2) keyboard navigation, (3) primary interactive actions. Evolution signal filed: https://github.com/ievo-ai/curator/issues/9
- **Convention-documentation gap risk (2026-03-04)**: A new `.ievo/research/` directory and naming convention were established in a session without updating the pipeline reference document. The user had to point this out explicitly in a later session. Root cause: no rule existed requiring convention documentation to happen atomically with structure creation — the pipeline reference was treated as a place for user-requested rules, not as a proactive living document. Rule added to CLAUDE.md: "Convention documentation is atomic." Decision D-021. Evolution signal filed: https://github.com/ievo-ai/curator/issues/10
- **Context-document pollution risk (2026-03-04)**: An ASCII diagram was added to a context-loaded file (auto-loaded into every agent session). User rejected immediately — visual artifacts inflate context with no benefit to agent reasoning. Root cause: no rule distinguished between files that serve agent context loading (machine-actionable rules only) and files that serve human documentation (diagrams, flowcharts appropriate). Agent classified destination by topic relevance only, not file purpose. Rule added to CLAUDE.md: "Context-loaded files stay concise." Decision D-022. Evolution signal filed: https://github.com/ievo-ai/curator/issues/11
- **Narrow-scope PR diagnosis risk (2026-03-03)**: When asked "why is the PR blocked?", the agent checked only CI status, found a failure, and stopped. Two additional blockers (branch behind base, reviewer change requests) required two further user prompts to surface. PR health diagnosis must collect all blocking signals — CI, merge state, reviewer decisions, branch freshness — before acting on any. Decision recorded in D-015. Evolution signal filed: https://github.com/ievo-ai/curator/issues/5
