# ALIVE — Self-Evolving AI Agent

## Project Context
Alive is an open-source AI agent that builds its own skills when it encounters 
tasks it can't perform. Unlike OpenClaw (pre-built skills) or Yunjue Agent 
(benchmark-focused), Alive is a PERSONAL agent that grows uniquely for each user.

## Architecture Principles
- Skills are plain Python files in ~/.alive/skills/<name>/
- Each skill has: skill.py, test_skill.py, metadata.json, SKILL.md
- The skill builder writes code, tests it in sandbox, retries on failure (max 5)
- The planner decomposes requests into capability needs before execution
- All state in SQLite at ~/.alive/alive.db
- Multi-provider LLM support (Claude, OpenAI, Ollama, DeepSeek)

## Code Style
- Python 3.11+, type hints everywhere
- async where beneficial (LLM calls), sync for simplicity elsewhere
- rich library for all terminal output (spinners, tables, panels, trees)
- No classes where functions suffice. Keep it simple.
- Error messages should be helpful and suggest next steps

## Key Design Decisions
- Skills run in subprocess with 60s timeout, NOT in-process
- Dependencies installed in a shared venv at ~/.alive/venv/
- The LLM provider is configurable via ALIVE_PROVIDER env var
- Default provider: claude (falls back to ollama if no API key)
- Skill metadata.json tracks: created_at, times_used, success_rate, 
  last_used, dependencies, description, confidence_score

## Current Status
- [ ] Project scaffold
- [ ] CLI with typer + rich
- [ ] LLM provider abstraction
- [ ] Skill registry
- [ ] Skill builder (Self-Extension Engine)
- [ ] Sandbox executor
- [ ] Planner
- [ ] Composer (skill chaining)
- [ ] Self-model
- [ ] Dream log
- [ ] Skill sharing (export/import)
- [ ] README with demo GIFs
- [ ] Tests
- [ ] PyPI publish