adelie-ai 0.1.0 → 0.1.2

package/README.md

@@ -1,335 +1,413 @@
-<p align="center">
-  <img src="docs/adelie_logo.jpeg" alt="Adelie Logo" width="200" />
-</p>
-
-<h1 align="center">Adelie</h1>
-
-<p align="center">
-  <strong>Self-Communicating Autonomous AI Loop System</strong><br/>
-  An AI orchestrator that plans, codes, reviews, tests, deploys, and evolves — autonomously.
-</p>
-
-<p align="center">
-  <img src="https://img.shields.io/badge/python-3.10+-blue?logo=python" alt="Python 3.10+" />
-  <img src="https://img.shields.io/badge/LLM-Gemini%20%7C%20Ollama-orange" alt="LLM Support" />
-  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License" />
-  <img src="https://img.shields.io/badge/tests-374%20passed-brightgreen" alt="Tests" />
-</p>
-
----
-
-## What is Adelie?
-
-Adelie is an **autonomous AI loop system** that orchestrates multiple specialized AI agents to build, maintain, and evolve software projects — with minimal human intervention.
-
-Think of it as an AI team that continuously works on your project:
-
-| Agent | Role |
-|-------|------|
-| **Expert AI** | Makes strategic decisions, dispatches tasks, manages state |
-| **Writer AI** | Creates and maintains the Knowledge Base (documentation) |
-| **Coder AI** | Writes actual source code in a layered architecture |
-| **Reviewer AI** | Reviews code quality, feeds back to coders |
-| **Tester AI** | Runs tests, reports failures back for fixes |
-| **Runner AI** | Builds, deploys, and runs the project |
-| **Monitor AI** | Checks system health, triggers restarts |
-| **Analyst AI** | Provides project-level insights and analysis |
-| **Research AI** | Searches the web for external information |
-| **Scanner AI** | Scans existing codebases on first run |
-
-All agents communicate through a **file-based Knowledge Base** and are coordinated by the **Orchestrator** — an endless loop with a built-in state machine.
-
----
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────┐
-│                   ORCHESTRATOR                       │
-│                                                     │
-│   ┌──────────┐    ┌──────────┐    ┌──────────────┐ │
-│   │ Writer AI│───>│Expert AI │───>│ Coder Manager│ │
-│   └──────────┘    └──────────┘    └──────┬───────┘ │
-│        │               │                 │         │
-│        v               │          ┌──────┴──────┐  │
-│   ┌──────────┐         │          │  Layer 0-2  │  │
-│   │Knowledge │         │          │   Coders    │  │
-│   │   Base   │<────────┘          └──────┬──────┘  │
-│   └──────────┘                           │         │
-│                                          v         │
-│   ┌──────────┐  ┌──────────┐  ┌──────────────────┐│
-│   │ Reviewer │  │ Tester   │  │ Runner / Monitor ││
-│   │    AI    │  │    AI    │  │       AI         ││
-│   └──────────┘  └──────────┘  └──────────────────┘│
-│                                                     │
-│   ┌──────────────────────────────────────────────┐ │
-│   │  Loop Detector │ Scheduler │ Process Supv.   │ │
-│   └──────────────────────────────────────────────┘ │
-└─────────────────────────────────────────────────────┘
-```
-
----
-
-## Project Lifecycle (Phases)
-
-Adelie evolves your project through 6 phases:
-
-```
-INITIAL ──> MID ──> MID_1 ──> MID_2 ──> LATE ──> EVOLVE
-Planning    Coding   Testing   Optimizing  Maintaining  Autonomous
-```
-
-| Phase | Focus | Coder Layers |
-|-------|-------|-------------|
-| Initial | Documentation, architecture, roadmap | None |
-| Mid | Implementation, feature coding | Layer 0 (features) |
-| Mid-1 | Integration, testing, roadmap check | Layer 0-1 (+ connectors) |
-| Mid-2 | Stabilization, optimization, deployment | Layer 0-2 (+ infra) |
-| Late | Maintenance, new features | All layers |
-| Evolve | Autonomous evolution, self-improvement | All layers |
-
-Phase transitions are **gated** by quality metrics (KB file count, test pass rate, review scores) and confirmed by the Expert AI.
-
----
-
-## Safety Harnesses
-
-Adelie includes multiple built-in safety mechanisms:
-
-| Harness | Purpose |
-|---------|---------|
-| **Loop Detector** | Detects 5 types of repetitive patterns with escalating interventions |
-| **Phase Gates** | Prevents premature transitions with quality thresholds |
-| **Context Budget** | Per-agent token budgets prevent unbounded prompt growth |
-| **Process Supervisor** | Timeout enforcement, orphan cleanup, concurrent limits |
-| **Reviewer Loop** | Code review → feedback → retry cycle (max 2 retries) |
-| **Tester Loop** | Test failure → coder fix → re-test cycle (max 2 retries) |
-| **Expert Fallback** | JSON retry + regex extraction + safe fallback decision |
-
----
-
-## Quick Start
-
-### Prerequisites
-
-- **Python 3.10+**
-- **Node.js 16+** (for the CLI wrapper)
-- **Gemini API key** or **Ollama** running locally
-
-### Installation
-
-```bash
-# Install via npm (recommended)
-npm install -g adelie
-
-# Or install from source
-git clone https://github.com/kimhyunbin/Adelie.git
-cd Adelie
-npm install -g .
-```
-
-### Setup
-
-```bash
-# Initialize a workspace in your project directory
-cd /path/to/your/project
-adelie init
-
-# Configure LLM provider
-adelie config --provider gemini --api-key YOUR_GEMINI_API_KEY
-
-# Or use Ollama (local, free)
-adelie config --provider ollama --model gemma3:12b
-
-# Set display language (ko or en)
-adelie config --lang en
-```
-
-### Run
-
-```bash
-# Start the autonomous AI loop
-adelie run --goal "Build a REST API for task management"
-
-# Or run a single cycle
-adelie run once --goal "Analyze and document the codebase"
-```
-
----
-
-## CLI Reference
-
-```
-Workspace
-  adelie init [dir]              Initialize workspace (default: current dir)
-  adelie ws                      List all workspaces
-  adelie ws remove <N>           Remove workspace #N
-
-Run
-  adelie run --goal "..."        Start AI loop
-  adelie run ws <N>              Resume loop in workspace #N
-  adelie run once --goal "..."   Run exactly one cycle
-
-Configuration
-  adelie config                  Show current config
-  adelie config --provider ...   Switch LLM provider (gemini/ollama)
-  adelie config --model ...      Set model name
-  adelie config --interval N     Set loop interval (seconds)
-  adelie config --api-key KEY    Set Gemini API key
-  adelie config --lang ko|en     Set display language
-
-Monitoring
-  adelie status                  System health & provider status
-  adelie inform                  Generate project status report
-  adelie phase                   Show current project phase
-  adelie phase set <phase>       Set phase manually
-
-Knowledge Base
-  adelie kb                      Show KB file counts per category
-  adelie kb --clear-errors       Clear error files
-  adelie kb --reset              Reset entire KB (destructive)
-
-Project Management
-  adelie goal                    Show current project goal
-  adelie goal set "..."          Set project goal
-  adelie feedback "message"      Send feedback to the AI loop
-  adelie research "topic"        Search the web and save to KB
-  adelie git                     Show git status & recent commits
-  adelie metrics                 Show recent cycle metrics
-
-Ollama
-  adelie ollama list             List installed models
-  adelie ollama pull <model>     Download a model
-  adelie ollama run [model]      Interactive chat
-
-Telegram
-  adelie telegram setup          Setup bot token
-  adelie telegram start          Start Telegram bot
-```
-
----
-
-## Environment Variables
-
-All settings are stored in `.adelie/.env` (created by `adelie init`):
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `LLM_PROVIDER` | `gemini` | `gemini` or `ollama` |
-| `GEMINI_API_KEY` | — | Required for Gemini provider |
-| `GEMINI_MODEL` | `gemini-2.0-flash` | Gemini model name |
-| `OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama server URL |
-| `OLLAMA_MODEL` | `llama3.2` | Ollama model name |
-| `FALLBACK_MODELS` | — | Comma-separated fallback chain (e.g. `gemini:gemini-2.5-flash,ollama:llama3.2`) |
-| `LOOP_INTERVAL_SECONDS` | `30` | Seconds between loop cycles |
-| `ADELIE_LANGUAGE` | `ko` | Display language (`ko` or `en`) |
-
----
-
-## Knowledge Base Structure
-
-The KB uses 6 categories:
-
-```
-.adelie/workspace/
-├── skills/          # How-to guides, procedures, capabilities
-├── dependencies/    # External APIs, libraries, services
-├── errors/          # Known errors, root causes, recovery
-├── logic/           # Decision patterns, planning docs
-├── exports/         # Reports, roadmaps, outputs
-└── maintenance/     # System health, status updates
-```
-
-All KB files are Markdown with tag-based and semantic (embedding) retrieval.
-
----
-
-## Testing
-
-```bash
-# Run all tests
-python -m pytest tests/ -v
-
-# Run specific test file
-python -m pytest tests/test_orchestrator.py -v
-```
-
-Currently **374 tests** covering all agents, context engine, loop detection, scheduling, and more.
-
----
-
-## Project Structure
-
-```
-Adelie/
-├── adelie/                  # Core package
-│   ├── orchestrator.py      # Main loop controller (state machine)
-│   ├── cli.py               # CLI commands
-│   ├── config.py            # Configuration & env loading
-│   ├── i18n.py              # Internationalization (ko/en)
-│   ├── llm_client.py        # LLM abstraction (Gemini + Ollama)
-│   ├── scheduler.py         # Per-agent scheduling
-│   ├── phases.py            # Project lifecycle phases
-│   ├── hooks.py             # Event-driven plugin system
-│   ├── loop_detector.py     # Stuck-loop detection
-│   ├── context_engine.py    # Per-agent context assembly
-│   ├── context_compactor.py # Token budget enforcement
-│   ├── process_supervisor.py# Subprocess management
-│   ├── feedback_queue.py    # User feedback injection
-│   ├── git_ops.py           # Git auto-commit
-│   ├── web_search.py        # Web search for Research AI
-│   ├── kb/                  # Knowledge Base
-│   │   ├── retriever.py     # Tag + semantic KB retrieval
-│   │   └── embedding_store.py
-│   ├── agents/              # AI agents
-│   │   ├── writer_ai.py     # KB file generation
-│   │   ├── expert_ai.py     # Decision-making
-│   │   ├── coder_ai.py      # Code generation
-│   │   ├── coder_manager.py # Multi-layer coder orchestration
-│   │   ├── reviewer_ai.py   # Code review
-│   │   ├── tester_ai.py     # Test execution
-│   │   ├── runner_ai.py     # Build & deploy
-│   │   ├── monitor_ai.py    # Health checks
-│   │   ├── analyst_ai.py    # Project analysis
-│   │   ├── research_ai.py   # Web research
-│   │   ├── scanner_ai.py    # Codebase scanning
-│   │   └── inform_ai.py     # Status reports
-│   └── integrations/
-│       └── telegram_bot.py  # Telegram integration
-├── tests/                   # 374 tests
-├── bin/                     # Node.js CLI wrapper
-├── scripts/                 # Install scripts
-├── requirements.txt         # Python dependencies
-└── package.json             # npm package config
-```
-
----
-
-## How It Works
-
-Each orchestrator cycle runs these steps:
-
-1. **Writer AI** creates/updates Knowledge Base files
-2. **Expert AI** reads the KB and makes a structured decision (JSON)
-3. **Research AI** searches the web if the Expert requested external info
-4. **Coder Manager** dispatches code generation tasks by layer
-5. **Reviewer AI** reviews the generated code; retries on failure
-6. **Staging → Project** promotes approved code to the project
-7. **Tester AI** runs tests; retries on failure
-8. **Runner AI** builds and deploys
-9. **Monitor AI** checks health; restarts if needed
-10. **Phase Gates** check if the project is ready for the next phase
-
-The loop runs continuously until shutdown, with the **Scheduler** controlling how often each agent runs and the **Loop Detector** intervening when the system gets stuck.
-
----
-
-## License
-
-MIT — see [LICENSE](./LICENSE) for details.
-
----
-
-<p align="center">
-  Made with Adelie
-</p>
+<p align="center">
+  <img src="docs/adelie_logo.jpeg" alt="Adelie Logo" width="200" />
+</p>
+
+<h1 align="center">Adelie</h1>
+
+<p align="center">
+  <strong>Self-Communicating Autonomous AI Loop System</strong><br/>
+  An AI orchestrator that plans, codes, reviews, tests, deploys, and evolves — autonomously.
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.10+-blue?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.10+" />
+  <img src="https://img.shields.io/badge/LLM-Gemini%20%7C%20Ollama-orange?style=for-the-badge" alt="LLM Support" />
+  <img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="MIT License" />
+  <img src="https://img.shields.io/badge/tests-183%20passed-brightgreen?style=for-the-badge" alt="Tests" />
+</p>
+
+<p align="center">
+  <a href="#-quick-start">Quick Start</a> ·
+  <a href="#-architecture">Architecture</a> ·
+  <a href="#-features">Features</a> ·
+  <a href="#-cli-reference">CLI</a> ·
+  <a href="#-testing">Testing</a> ·
+  <a href="#-license">License</a>
+</p>
+
+---
+
+## 🤔 What is Adelie?
+
+Adelie is an **autonomous AI loop system** that orchestrates 10 specialized AI agents to build, maintain, and evolve software projects — with minimal human intervention.
+
+Think of it as a full AI development team running 24/7:
+
+```
+ 🧠 Expert AI    →  Strategic decisions & task dispatch
+ ✍️  Writer AI    →  Knowledge Base documentation
+ 💻 Coder AI     →  Code generation (3-layer architecture)
+ 🔍 Reviewer AI  →  Code quality review & feedback
+ 🧪 Tester AI    →  Test execution & failure reporting
+ 🚀 Runner AI    →  Build & deployment
+ 📡 Monitor AI   →  System health monitoring
+ 📊 Analyst AI   →  Project insights & analysis
+ 🔎 Research AI  →  Web search for external info
+ 🔬 Scanner AI   →  Codebase scanning on first run
+```
+
+All agents communicate through a **file-based Knowledge Base** and are coordinated by the **Orchestrator** — an endless loop with a built-in state machine.
+
+---
+
+## ✨ Features
+
+### 🎯 Core
+
+- **10 Specialized Agents** — Each with a focused role, scheduled independently
+- **6-Phase Project Lifecycle** — `INITIAL → MID → MID_1 → MID_2 → LATE → EVOLVE`
+- **Layered Code Generation** — Layer 0 (features) → Layer 1 (connectors) → Layer 2 (infra)
+- **Knowledge Base** — Tag-based & semantic retrieval across 6 categories
+- **Multi-LLM** — Gemini + Ollama with automatic fallback chains
+
+### 🛡️ Safety
+
+- **Loop Detector** — 5 stuck-pattern types with escalating interventions
+- **Phase Gates** — Quality-metric thresholds (KB count, test rate, review scores)
+- **Context Budget** — Per-agent token limits prevent unbounded growth
+- **Process Supervisor** — Timeout enforcement, orphan cleanup, concurrency limits
+
+### 🔌 Extensibility (New in Phase 2-3)
+
+| Feature | Description |
+|---------|-------------|
+| 💾 **Checkpoint System** | Auto-snapshot before file promotion, instant rollback |
+| 🐳 **Docker Sandboxing** | Configurable workspace access, network isolation, security blocklist |
+| 🌐 **REST Gateway** | HTTP API: `/api/status`, `/api/tools`, `/api/control` |
+| 🧩 **Skill Registry** | Install/update/uninstall skills from Git or local dirs |
+| 📡 **Multichannel** | `ChannelProvider` ABC — Discord, Slack, and custom channels |
+| 🤝 **A2A Protocol** | Agent-to-Agent HTTP API for external agent integration |
+| 🔧 **MCP Support** | Model Context Protocol for external tool ecosystems |
+
+---
+
+## 🏗️ Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        ORCHESTRATOR                              │
+│                                                                  │
+│   ┌──────────┐    ┌──────────┐    ┌──────────────┐              │
+│   │ Writer AI│───>│Expert AI │───>│ Coder Manager│              │
+│   └──────────┘    └──────────┘    └──────┬───────┘              │
+│        │               │                 │                       │
+│        v               │          ┌──────┴──────┐               │
+│   ┌──────────┐         │          │  Layer 0-2  │               │
+│   │Knowledge │         │          │   Coders    │               │
+│   │   Base   │<────────┘          └──────┬──────┘               │
+│   └──────────┘                           │                       │
+│                                          v                       │
+│   ┌──────────┐  ┌──────────┐  ┌──────────────────┐             │
+│   │ Reviewer │  │ Tester   │  │ Runner / Monitor │             │
+│   │    AI    │  │    AI    │  │       AI         │             │
+│   └──────────┘  └──────────┘  └──────────────────┘             │
+│                                                                  │
+│   ┌─────────────────────────────────────────────────────────┐   │
+│   │ Loop Detector │ Scheduler │ Process Supervisor          │   │
+│   ├─────────────────────────────────────────────────────────┤   │
+│   │ Checkpoint    │ Sandbox   │ Gateway │ A2A │ Channels    │   │
+│   └─────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🔄 Project Lifecycle
+
+Adelie evolves your project through **6 phases**, each gated by quality metrics:
+
+```
+INITIAL ──> MID ──> MID_1 ──> MID_2 ──> LATE ──> EVOLVE
+Planning    Code    Test      Optimize  Maintain  Autonomous
+```
+
+| Phase | Focus | Coder Layers |
+|-------|-------|-------------|
+| Initial | Documentation, architecture, roadmap | — |
+| Mid | Implementation, feature coding | Layer 0 |
+| Mid-1 | Integration, testing | Layer 0-1 |
+| Mid-2 | Stabilization, optimization | Layer 0-2 |
+| Late | Maintenance, new features | All |
+| Evolve | Self-improvement | All |
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- **Python 3.10+**
+- **Node.js 16+** (for CLI wrapper)
+- **Gemini API key** or **Ollama** running locally
+
+### Installation
+
+```bash
+# Install via npm (recommended)
+npm install -g adelie-ai
+
+# Or install from source
+git clone https://github.com/kimhyunbin/Adelie.git
+cd Adelie
+pip install -r requirements.txt
+npm install -g .
+```
+
+### Setup
+
+```bash
+# Initialize workspace
+cd /path/to/your/project
+adelie init
+
+# Configure LLM provider
+adelie config --provider gemini --api-key YOUR_GEMINI_API_KEY
+
+# Or use Ollama (local, free)
+adelie config --provider ollama --model gemma3:12b
+```
+
+### Run
+
+```bash
+# Start the autonomous AI loop
+adelie run --goal "Build a REST API for task management"
+
+# Single cycle
+adelie run once --goal "Analyze and document the codebase"
+```
+
+---
+
+## 💻 CLI Reference
+
+```
+Workspace
+  adelie init [dir]              Initialize workspace
+  adelie ws                      List all workspaces
+  adelie ws remove <N>           Remove workspace #N
+
+Run
+  adelie run --goal "..."        Start AI loop
+  adelie run ws <N>              Resume loop in workspace #N
+  adelie run once --goal "..."   Run one cycle
+
+Configuration
+  adelie config                  Show current config
+  adelie config --provider ...   Switch LLM (gemini/ollama)
+  adelie config --model ...      Set model name
+  adelie config --interval N     Loop interval (seconds)
+  adelie config --api-key KEY    Set Gemini API key
+  adelie config --lang ko|en     Display language
+
+Monitoring
+  adelie status                  System health
+  adelie inform                  Project status report
+  adelie phase                   Show phase
+  adelie phase set <phase>       Set phase manually
+  adelie metrics                 Cycle metrics
+
+Knowledge Base
+  adelie kb                      KB file counts
+  adelie kb --clear-errors       Clear error files
+  adelie kb --reset              Reset KB (destructive)
+
+Project
+  adelie goal                    Show project goal
+  adelie goal set "..."          Set project goal
+  adelie feedback "message"      Send feedback to AI loop
+  adelie research "topic"        Web search → KB
+  adelie git                     Git status & recent commits
+
+Ollama
+  adelie ollama list             List models
+  adelie ollama pull <model>     Download model
+  adelie ollama run [model]      Interactive chat
+
+Telegram
+  adelie telegram setup          Setup bot token
+  adelie telegram start          Start Telegram bot
+```
+
+---
+
+## 🔧 Configuration
+
+### Environment Variables
+
+All settings stored in `.adelie/.env`:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LLM_PROVIDER` | `gemini` | `gemini` or `ollama` |
+| `GEMINI_API_KEY` | — | Required for Gemini |
+| `GEMINI_MODEL` | `gemini-2.0-flash` | Gemini model |
+| `OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama URL |
+| `OLLAMA_MODEL` | `llama3.2` | Ollama model |
+| `FALLBACK_MODELS` | — | Fallback chain (e.g. `gemini:flash,ollama:llama3.2`) |
+| `LOOP_INTERVAL_SECONDS` | `30` | Loop interval |
+| `ADELIE_LANGUAGE` | `ko` | Display language |
+
+### Docker Sandbox Config
+
+Optional `.adelie/sandbox.json`:
+
+```json
+{
+  "docker": {
+    "image": "adelie-sandbox:latest",
+    "workspaceAccess": "rw",
+    "network": "none",
+    "memoryLimit": "512m",
+    "cpuLimit": 1.0,
+    "readOnlyRoot": false
+  }
+}
+```
+
+### Skills
+
+Place skills in `.adelie/skills/<name>/SKILL.md`:
+
+```yaml
+---
+name: react-specialist
+description: React/TypeScript best practices
+agents: [coder, reviewer]
+trigger: auto
+---
+# Instructions
+Use functional components...
+```
+
+---
+
+## 🧪 Testing
+
+```bash
+# Run all tests
+python -m pytest tests/ -v
+
+# Specific modules
+python -m pytest tests/test_checkpoint.py -v
+python -m pytest tests/test_gateway.py -v
+python -m pytest tests/test_a2a.py -v
+```
+
+**183 tests** across 8 test suites:
+
+| Suite | Tests | Coverage |
+|-------|-------|----------|
+| MCP Client | 35 | MCP server connection, tool discovery |
+| Tool Registry | 20 | Tool registration, categories, user tools |
+| Checkpoint | 16 | Create, restore, prune, metadata |
+| Docker Sandbox | 26 | Config, bind safety, Docker wrapping |
+| Gateway API | 18 | REST endpoints, auth, CORS |
+| Skill Registry | 19 | Install, uninstall, manifest, helpers |
+| Multichannel | 24 | Providers, router, broadcast, events |
+| A2A Protocol | 25 | Task lifecycle, persistence, HTTP API |
+
+---
+
+## 📁 Project Structure
+
+```
+Adelie/
+├── adelie/                     # Core package
+│   ├── orchestrator.py         # Main loop controller (state machine)
+│   ├── cli.py                  # CLI commands
+│   ├── config.py               # Configuration & env loading
+│   ├── llm_client.py           # LLM abstraction (Gemini + Ollama)
+│   ├── checkpoint.py           # 💾 Checkpoint system
+│   ├── sandbox.py              # 🐳 Docker/Seatbelt sandboxing
+│   ├── gateway.py              # 🌐 REST API gateway
+│   ├── skill_manager.py        # 🧩 Skill loading & registry
+│   ├── scheduler.py            # Per-agent scheduling
+│   ├── phases.py               # Project lifecycle phases
+│   ├── hooks.py                # Event-driven plugin system
+│   ├── loop_detector.py        # Stuck-loop detection
+│   ├── context_engine.py       # Per-agent context assembly
+│   ├── process_supervisor.py   # Subprocess management
+│   ├── feedback_queue.py       # User feedback injection
+│   ├── channels/               # 📡 Multichannel abstraction
+│   │   ├── base.py             #   ChannelProvider ABC
+│   │   ├── discord.py          #   Discord integration
+│   │   ├── slack.py            #   Slack integration
+│   │   └── router.py           #   Multi-channel routing
+│   ├── a2a/                    # 🤝 Agent-to-Agent protocol
+│   │   ├── types.py            #   Task/Event types
+│   │   ├── server.py           #   A2A HTTP server
+│   │   └── persistence.py      #   Task persistence
+│   ├── agents/                 # AI agents (10 specialized)
+│   │   ├── expert_ai.py
+│   │   ├── writer_ai.py
+│   │   ├── coder_ai.py
+│   │   ├── reviewer_ai.py
+│   │   ├── tester_ai.py
+│   │   ├── runner_ai.py
+│   │   ├── monitor_ai.py
+│   │   ├── analyst_ai.py
+│   │   ├── research_ai.py
+│   │   └── scanner_ai.py
+│   └── kb/                     # Knowledge Base
+│       ├── retriever.py
+│       └── embedding_store.py
+├── tests/                      # 183 tests
+├── bin/                        # Node.js CLI wrapper
+├── requirements.txt            # Python dependencies
+└── package.json                # npm config
+```
+
+---
+
+## ⚙️ How It Works
+
+Each orchestrator cycle runs these steps:
+
+1. **Writer AI** creates/updates Knowledge Base files
+2. **Expert AI** reads KB and makes structured decisions (JSON)
+3. **Research AI** searches the web if requested
+4. **Coder Manager** dispatches code generation by layer
+5. **Reviewer AI** reviews code; retries on failure
+6. **💾 Checkpoint** snapshots current files before promotion
+7. **Staging → Project** promotes approved code
+8. **Tester AI** runs tests; retries on failure
+9. **Runner AI** builds and deploys
+10. **Monitor AI** checks health; restarts if needed
+11. **Phase Gates** evaluate readiness for next phase
+
+The loop runs continuously with the **Scheduler** controlling agent frequency and the **Loop Detector** intervening when the system gets stuck.
+
+---
+
+## 🗺️ Roadmap
+
+- [x] **Phase 1** — MCP Server Integration
+- [x] **Phase 2** — Checkpoint System, Docker Sandboxing, REST Gateway
+- [x] **Phase 3** — Skill Registry, Multichannel, A2A Protocol
+- [ ] **Phase 4** — VS Code Extension, Web Dashboard, Plugin Marketplace
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit Pull Requests.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Run tests (`python -m pytest tests/ -v`)
+4. Commit your changes (`git commit -m 'Add amazing feature'`)
+5. Push to the branch (`git push origin feature/amazing-feature`)
+6. Open a Pull Request
+
+---
+
+## 📄 License
+
+MIT — see [LICENSE](./LICENSE) for details.
+
+---
+
+<p align="center">
+  <sub>Built with 🐧 Adelie — the penguin that codes</sub>
+</p>

package/adelie/interactive.py

@@ -14,7 +14,13 @@ Layout:
 
 from __future__ import annotations
 
-import readline  # noqa: F401 — enables arrow-key editing in input()
+try:
+    import readline  # noqa: F401 — enables arrow-key editing in input()
+except ImportError:
+    try:
+        import pyreadline3  # noqa: F401 — Windows alternative
+    except ImportError:
+        pass  # arrow-key editing won't work, but no crash
 import shutil
 import signal
 import sys

package/bin/adelie.js

@@ -53,7 +53,9 @@ function ensureVenv() {
     const pip = IS_WIN
       ? path.join(VENV_DIR, "Scripts", "pip")
       : path.join(VENV_DIR, "bin", "pip");
-    execSync(`"${pip}" install -r "${REQUIREMENTS}"`, { stdio: "inherit" });
+    const pipEnv = { ...process.env };
+    if (IS_WIN) pipEnv.PYTHONUTF8 = "1";
+    execSync(`"${pip}" install -r "${REQUIREMENTS}"`, { stdio: "inherit", env: pipEnv });
     console.log("[adelie] Python environment ready.");
   } catch (err) {
     console.error(`[adelie] ERROR: Failed to set up Python environment: ${err.message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adelie-ai",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Adelie — Self-Communicating Autonomous AI Loop CLI",
   "bin": {
     "adelie": "bin/adelie.js"
@@ -30,11 +30,10 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/kimhyunbin/Adelie.git"
+    "url": "git+https://github.com/Ade1ie/adelie.git"
   },
-  "homepage": "https://github.com/kimhyunbin/Adelie",
   "bugs": {
-    "url": "https://github.com/kimhyunbin/Adelie/issues"
+    "url": "https://github.com/Ade1ie/adelie/issues"
   },
   "engines": {
     "node": ">=16.0.0"

package/requirements.txt

@@ -1,20 +1,20 @@
-# ── Core (required) ──────────────────────────────────────────────────────────
-rich>=13.0.0
-python-dotenv>=1.0.0
-requests>=2.28.0
-
-# ── LLM Providers ───────────────────────────────────────────────────────────
-google-genai>=1.0.0
-
-# ── MCP (Model Context Protocol) ────────────────────────────────────────────
-# mcp>=1.0.0  # Optional: install for SSE transport support
-
-# ── Spec Loader (PDF support) ───────────────────────────────────────────────
-PyPDF2>=3.0.0
-
-# ── Browser Search Fallback (optional — installed on demand) ────────────────
-# playwright>=1.40.0
-beautifulsoup4>=4.12.0
-
-# ── Integrations (optional) ─────────────────────────────────────────────────
-# python-telegram-bot>=20.0
+# Core (required)
+rich>=13.0.0
+python-dotenv>=1.0.0
+requests>=2.28.0
+
+# LLM Providers
+google-genai>=1.0.0
+
+# MCP (Model Context Protocol)
+# mcp>=1.0.0  # Optional: install for SSE transport support
+
+# Spec Loader (PDF support)
+PyPDF2>=3.0.0
+
+# Browser Search Fallback (optional)
+# playwright>=1.40.0
+beautifulsoup4>=4.12.0
+
+# Integrations (optional)
+# python-telegram-bot>=20.0

package/scripts/postinstall.js

@@ -1,61 +1,150 @@
-#!/usr/bin/env node
-
-/**
- * scripts/postinstall.js — Runs after npm install
- *
- * Creates a Python virtual environment and installs requirements.
- */
-
-const { execSync } = require("child_process");
-const path = require("path");
-const fs = require("fs");
-
-const PKG_ROOT = path.resolve(__dirname, "..");
-const VENV_DIR = path.join(PKG_ROOT, ".venv");
-const REQUIREMENTS = path.join(PKG_ROOT, "requirements.txt");
-const IS_WIN = process.platform === "win32";
-const PYTHON_BIN = IS_WIN
-  ? path.join(VENV_DIR, "Scripts", "python.exe")
-  : path.join(VENV_DIR, "bin", "python");
-
-if (fs.existsSync(PYTHON_BIN)) {
-  console.log("[adelie] Python environment already exists, skipping setup.");
-  process.exit(0);
-}
-
-// Find system Python 3
-const candidates = IS_WIN ? ["python", "python3", "py"] : ["python3", "python"];
-let sysPython = null;
-
-for (const cmd of candidates) {
-  try {
-    const ver = execSync(`${cmd} --version 2>&1`, { encoding: "utf-8" }).trim();
-    if (ver.includes("Python 3")) {
-      sysPython = cmd;
-      break;
-    }
-  } catch {}
-}
-
-if (!sysPython) {
-  console.error("[adelie] ERROR: Python 3 is required but not found.");
-  console.error("         Install it from: https://www.python.org/downloads/");
-  console.error("         After installing Python 3, run: npm rebuild adelie");
-  process.exit(1);
-}
-
-console.log(`[adelie] Creating Python venv with ${sysPython}...`);
-
-try {
-  execSync(`${sysPython} -m venv "${VENV_DIR}"`, { stdio: "inherit" });
-  const pip = IS_WIN
-    ? path.join(VENV_DIR, "Scripts", "pip")
-    : path.join(VENV_DIR, "bin", "pip");
-  execSync(`"${pip}" install -q -r "${REQUIREMENTS}"`, { stdio: "inherit" });
-  console.log("[adelie] Python environment ready.");
-} catch (err) {
-  console.error(`[adelie] ERROR: Failed to set up Python environment.`);
-  console.error(`         ${err.message}`);
-  console.error("         Try manually: python3 -m venv .venv && .venv/bin/pip install -r requirements.txt");
-  process.exit(1);
-}
+#!/usr/bin/env node
+
+/**
+ * scripts/postinstall.js — Runs after npm install
+ *
+ * Creates a Python virtual environment, installs requirements,
+ * and shows a welcome screen with initial setup guide.
+ */
+
+const { execSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const PKG_ROOT = path.resolve(__dirname, "..");
+const VENV_DIR = path.join(PKG_ROOT, ".venv");
+const REQUIREMENTS = path.join(PKG_ROOT, "requirements.txt");
+const IS_WIN = process.platform === "win32";
+const PYTHON_BIN = IS_WIN
+  ? path.join(VENV_DIR, "Scripts", "python.exe")
+  : path.join(VENV_DIR, "bin", "python");
+
+// ── Color helpers ────────────────────────────────────────────────────────────
+const c = {
+  reset:    "\x1b[0m",
+  bold:     "\x1b[1m",
+  dim:      "\x1b[2m",
+  italic:   "\x1b[3m",
+  underline:"\x1b[4m",
+  cyan:     "\x1b[36m",
+  green:    "\x1b[32m",
+  yellow:   "\x1b[33m",
+  blue:     "\x1b[34m",
+  magenta:  "\x1b[35m",
+  white:    "\x1b[97m",
+  gray:     "\x1b[90m",
+  bgBlue:   "\x1b[44m",
+  bgMagenta:"\x1b[45m",
+  bgCyan:   "\x1b[46m",
+};
+
+function showWelcome() {
+  const banner = `
+${c.cyan}${c.bold}
+    ___       __     ___
+   /   | ____/ /__  / (_)__
+  / /| |/ __  / _ \\/ / / _ \\
+ / ___ / /_/ /  __/ / /  __/
+/_/  |_\\__,_/\\___/_/_/\\___/
+${c.reset}
+${c.bold}${c.white}  Self-Communicating Autonomous AI Loop System${c.reset}
+${c.dim}${c.cyan}  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${c.reset}
+`;
+
+  const info = `
+  ${c.green}${c.bold}✔ Installation complete!${c.reset}
+
+  ${c.bold}${c.white}🚀 Quick Start${c.reset}
+  ${c.gray}─────────────────────────────────────────${c.reset}
+
+  ${c.yellow}${c.bold}1.${c.reset} ${c.white}Initialize a workspace${c.reset}
+     ${c.cyan}$ ${c.bold}adelie init${c.reset}
+
+  ${c.yellow}${c.bold}2.${c.reset} ${c.white}Configure your LLM provider${c.reset}
+     ${c.cyan}$ ${c.bold}adelie config --provider gemini --api-key YOUR_KEY${c.reset}
+     ${c.dim}or for local Ollama:${c.reset}
+     ${c.cyan}$ ${c.bold}adelie config --provider ollama --model gemma3:12b${c.reset}
+
+  ${c.yellow}${c.bold}3.${c.reset} ${c.white}Start the autonomous AI loop${c.reset}
+     ${c.cyan}$ ${c.bold}adelie run --goal "Build a REST API"${c.reset}
+
+  ${c.gray}─────────────────────────────────────────${c.reset}
+
+  ${c.bold}${c.white}📖 Useful Commands${c.reset}
+  ${c.dim}  adelie status${c.reset}      ${c.gray}— System health check${c.reset}
+  ${c.dim}  adelie phase${c.reset}       ${c.gray}— Current project phase${c.reset}
+  ${c.dim}  adelie kb${c.reset}          ${c.gray}— Knowledge Base summary${c.reset}
+  ${c.dim}  adelie --help${c.reset}      ${c.gray}— Full command reference${c.reset}
+
+  ${c.gray}─────────────────────────────────────────${c.reset}
+  ${c.magenta}${c.bold}♥${c.reset}  ${c.dim}GitHub: ${c.underline}https://github.com/Ade1ie/adelie${c.reset}
+  ${c.blue}${c.bold}★${c.reset}  ${c.dim}npm:    ${c.underline}https://www.npmjs.com/package/adelie-ai${c.reset}
+`;
+
+  console.log(banner);
+  console.log(info);
+}
+
+// ── Python setup ─────────────────────────────────────────────────────────────
+
+if (fs.existsSync(PYTHON_BIN)) {
+  showWelcome();
+  process.exit(0);
+}
+
+// Find system Python 3
+const candidates = IS_WIN ? ["python", "python3", "py"] : ["python3", "python"];
+let sysPython = null;
+
+for (const cmd of candidates) {
+  try {
+    const ver = execSync(`${cmd} --version 2>&1`, { encoding: "utf-8" }).trim();
+    if (ver.includes("Python 3")) {
+      sysPython = cmd;
+      break;
+    }
+  } catch {}
+}
+
+if (!sysPython) {
+  console.error(`\n  ${c.yellow}${c.bold}⚠  Python 3 is required but not found.${c.reset}`);
+  console.error(`  ${c.dim}Install it from: ${c.underline}https://www.python.org/downloads/${c.reset}`);
+  console.error(`  ${c.dim}After installing, run: ${c.cyan}npm rebuild adelie-ai${c.reset}\n`);
+  process.exit(1);
+}
+
+console.log(`\n  ${c.cyan}${c.bold}⏳ Setting up Python environment...${c.reset}`);
+console.log(`  ${c.dim}Using: ${sysPython}${c.reset}\n`);
+
+try {
+  execSync(`${sysPython} -m venv "${VENV_DIR}"`, { stdio: "inherit" });
+
+  const pip = IS_WIN
+    ? path.join(VENV_DIR, "Scripts", "pip")
+    : path.join(VENV_DIR, "bin", "pip");
+
+  // Use --encoding utf-8 via env to avoid cp949 issues on Windows
+  const pipEnv = { ...process.env };
+  if (IS_WIN) {
+    pipEnv.PYTHONUTF8 = "1";
+  }
+
+  execSync(`"${pip}" install -q -r "${REQUIREMENTS}"`, {
+    stdio: "inherit",
+    env: pipEnv,
+  });
+
+  console.log(`  ${c.green}${c.bold}✔ Python environment ready.${c.reset}\n`);
+  showWelcome();
+} catch (err) {
+  console.error(`\n  ${c.yellow}${c.bold}⚠  Failed to set up Python environment.${c.reset}`);
+  console.error(`  ${c.dim}${err.message}${c.reset}`);
+  console.error(`  ${c.dim}Try manually:${c.reset}`);
+  if (IS_WIN) {
+    console.error(`  ${c.cyan}python -m venv .venv && .venv\\Scripts\\pip install -r requirements.txt${c.reset}`);
+  } else {
+    console.error(`  ${c.cyan}python3 -m venv .venv && .venv/bin/pip install -r requirements.txt${c.reset}`);
+  }
+  console.error("");
+  process.exit(1);
+}