@praveencs/agent 0.8.0 → 0.8.2

package/README.md

@@ -1,17 +1,51 @@
-# Agent Runtime
+# 🤖 Agent Runtime
 
-An autonomous, goal-oriented AI agent runtime with persistent memory, skill execution, and self-improvement capabilities. The agent acts as your digital employee, capable of breaking down high-level objectives into actionable tasks, executing them using a variety of skills, and learning from its experiences.
+> An autonomous, goal-oriented AI agent runtime with an interactive CLI, plugin ecosystem, and self-improvement capabilities.
 
----
+[![npm version](https://img.shields.io/npm/v/@praveencs/agent)](https://www.npmjs.com/package/@praveencs/agent)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+```
+$ agent
+
+  ╭────────────────────────────────────────────────╮
+  │  🤖 Agent Runtime v0.8.1                       │
+  │    Project: my-app                              │
+  │    Model: gpt-4o │ 3 skills │ 2 commands        │
+  ╰────────────────────────────────────────────────╯
+
+  Type a goal, a /command, or /help for help.
 
-## 🚀 Features
+  > Refactor the auth module to use JWT
+  ⠋ Thinking...
+  ⚡ fs.read(src/auth/handler.ts) ✓
+  ⚡ fs.write(src/auth/jwt.ts) ✓
+  ⚡ cmd.run(npm test) ✓
 
-- **🧠 Goal Decomposition**: Uses LLM reasoning to break complex, high-level objectives into specific, actionable tasks.
-- **⚡ Autonomous Execution**: Runs tasks in the background via a robust daemon process, respecting dependencies and priorities.
-- **💾 Persistent Memory**: SQLite-based semantic memory with FTS5 search. Stores facts, project context, and learned patterns across sessions.
-- **🛠️ Extensible Skill System**: Capabilities are defined by simple markdown prompts (`prompt.md`). Install skills from a hub or create your own.
-- **📊 Reporting**: Generates daily standup reports and executive summaries of activity and progress.
-- **❤️ Self-Improvement**: Tracks skill performance metrics and automatically attempts to patch/repair failing skills using the LLM.
+  ✓ Done (12.3s)
+
+  > /deploy-staging
+  Running command: deploy-staging...
+```
+
+---
+
+## ✨ Features
+
+| Category | Capabilities |
+|----------|-------------|
+| **🤖 Interactive CLI** | Conversational REPL with multi-turn context, slash commands, and tab completion |
+| **🧠 Goal Decomposition** | LLM-powered breakdown of complex objectives into dependency-aware task graphs |
+| **⚡ Autonomous Execution** | Background daemon processes tasks with retries, rollback, and verification |
+| **🛠️ Extensible Skills** | Markdown-based skill definitions—install from a hub or write your own |
+| **⚡ Lightweight Commands** | Quick goal templates as markdown files—no boilerplate needed |
+| **🪝 Lifecycle Hooks** | Intercept execution at 10 event points (before:tool, after:plan, etc.) |
+| **🔌 Plugin System** | Bundle skills, commands, and hooks into distributable packages |
+| **🔧 Multi-CLI Orchestration** | Delegate tasks to Cursor, Codex, Gemini, or Claude CLIs |
+| **💾 Persistent Memory** | SQLite + FTS5 semantic memory across sessions |
+| **❤️ Self-Improvement** | Monitors skill metrics and auto-patches failing skills |
+| **📊 Reporting** | Daily standup reports and AI-generated executive summaries |
+| **🔒 Policy Engine** | Permission-gated tool execution with human-in-the-loop approval |
 
 ---
 
@@ -21,181 +55,444 @@ An autonomous, goal-oriented AI agent runtime with persistent memory, skill exec
 npm install -g @praveencs/agent
 ```
 
-### Initial Configuration
-After installation, initialize the configuration:
+### Quick Start
+
+```bash
+# Initialize project configuration
+agent init
+
+# Launch interactive mode (recommended)
+agent
+
+# Or run a one-off goal
+agent run "Add input validation to the signup form"
+```
+
+### Configuration
+
+After `agent init`, a `.agent/` directory is created in your project with configuration, skills, commands, and hooks. Set your LLM provider API keys:
 
 ```bash
+# Set via environment variables
+export OPENAI_API_KEY=sk-...
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# Or configure directly
 agent config --init
 ```
 
-This will create a default configuration file (`~/.agent/config.json`) where you can set your LLM provider API keys (OpenAI, Anthropic, Azure, Ollama) and other preferences.
+---
+
+## 📖 Usage Guide
+
+### 1. Interactive Mode (Recommended)
+
+Type `agent` with no arguments to enter the **Interactive REPL**:
+
+```bash
+agent
+```
+
+You get a bordered welcome banner showing your project, model, and loaded extensions. Then just type naturally:
+
+```
+  > Add rate limiting to the /api/auth endpoint
+  > Now write tests for it
+  > /deploy-staging
+```
+
+The agent **remembers context** across turns—no need to repeat yourself.
+
+#### Slash Commands
+
+| Command | Action |
+|---------|--------|
+| `/help` | Show all available commands |
+| `/skills` | List installed skills with status |
+| `/commands` | List available lightweight commands |
+| `/hooks` | Show registered lifecycle hooks |
+| `/model` | Display current model and provider info |
+| `/compact` | Summarize conversation and free context |
+| `/clear` | Clear the terminal screen |
+| `/exit` | Exit interactive mode |
+
+Custom commands from `.agent/commands/` are also available as slash commands (e.g., `/deploy-staging`).
+
+**Tab completion** works on all slash commands—press `Tab` after `/`.
 
 ---
 
-## 📖 User Guide
+### 2. One-Shot Mode
 
-### 1. The Workflow
-The typical workflow follows a **Plan → Decompose → Execute → Report** cycle:
+Run a single goal without entering the REPL:
 
-1.  **Plan**: Tell the agent what you want to achieve.
-    ```bash
-    agent goal add "Create a personal blog with Next.js and PostgreSQL" --priority 1
-    # Output: Goal #1 created
-    ```
+```bash
+agent run "Refactor the database module to use connection pooling"
+agent run "Fix all TypeScript errors in the project"
+agent run deploy-staging          # Runs a named Command or Skill
+```
 
-2.  **Decompose**: Ask the agent to break it down.
-    ```bash
-    agent goal decompose 1
-    # Output: Goal decomposed into 5 tasks (Scaffold, DB Setup, Styling...)
-    ```
-    *The agent uses its LLM planner to analyze the goal and your available skills to create a task list.*
+---
 
-3.  **Execute**: Start the daemon to work on tasks autonomously.
-    ```bash
-    agent daemon start
-    ```
-    *The daemon runs in the background, processing tasks, handling retries, and logging activity.*
+### 3. Skills
 
-    You can check progress at any time:
-    ```bash
-    agent goal list           # See goal status
-    agent goal status 1       # See detailed task status for Goal #1
-    agent daemon status       # Check if the worker is running
-    ```
+Skills are reusable capabilities defined by markdown prompts and a `skill.json` manifest.
 
-4.  **Report**: Get a summary of what happened.
-    ```bash
-    agent report generate --summary
-    ```
-    *Generates a notification-style summary of completed work, new learnings, and any blockers.*
+```bash
+# List installed skills
+agent skills list
 
-### 2. Managing Skills
-Skills are the tools your agent uses (e.g., `git-commit`, `docker-deploy`, `file-write`).
+# Search the skill hub
+agent skills search "docker"
 
-- **List installed skills**:
-  ```bash
-  agent skills list
-  ```
+# Install a skill
+agent skills install <skill-name>
 
-- **Find new skills**:
-  ```bash
-  agent skills search "database"
-  agent skills browse
-  ```
+# Create a custom skill
+agent skills create my-new-skill
+# → Creates .agent/skills/my-new-skill/prompt.md
 
-- **Install a skill**:
-  ```bash
-  agent skills install <skill-name>
-  ```
+# Self-healing
+agent skills stats               # View success rates
+agent skills doctor my-skill     # Diagnose failures
+agent skills fix my-skill        # Auto-repair with LLM
+```
 
-- **Create a custom skill**:
-  ```bash
-  agent skills create my-new-skill
-  ```
-  *This creates a template at `.agent/skills/my-new-skill/prompt.md`. Edit this file to define what the skill does using natural language instructions for the LLM.*
+---
 
-- **Self-Repair (Doctor)**:
-  If a skill is failing, the agent can diagnose and fix it.
-  ```bash
-  agent skills stats               # View success rates
-  agent skills doctor my-skill     # Analyze error logs
-  agent skills fix my-skill        # Attempt AI auto-repair
-  ```
+### 4. Lightweight Commands
 
-### 3. Memory & Context
-The agent automatically saves important information (like "Project uses Tailwind CSS") to its memory. You can search or manage this manually.
+Commands are quick goal templates—just a markdown file. No `skill.json` needed.
 
-- **Search memory**:
-  ```bash
-  agent memory search "database credentials"
-  ```
-- **Add a fact**:
-  ```bash
-  agent memory add "The staging server IP is 10.0.0.5" --category fact
-  ```
+Create `.agent/commands/deploy-staging.md`:
 
+```markdown
 ---
+name: deploy-staging
+description: Deploy current branch to staging
+tools: [cmd.run, git.status, git.diff]
+---
+# Deploy to Staging
 
-## 🤖 CLI Command Reference
+Steps:
+1. Run `npm test` to verify all tests pass
+2. Run `npm run build` to create the production bundle
+3. Run `git push origin HEAD:staging` to trigger deployment
+```
 
-### General
-| Command | Description |
-|Str |---|
-| `agent run "<instruction>"` | Run a one-off instruction immediately |
-| `agent config --init` | Initialize configuration |
-| `agent doctor` | Check system health (dependencies, config) |
+Now use it:
+
+```bash
+agent run deploy-staging     # From CLI
+# or
+> /deploy-staging            # From interactive mode
+```
+
+The command's markdown body becomes the LLM prompt, and only the whitelisted tools are available.
+
+```bash
+agent commands list          # See all available commands
+```
+
+---
+
+### 5. Lifecycle Hooks
+
+Hooks intercept agent execution at every point. Define them in `.agent/hooks/hooks.json`:
+
+```json
+{
+  "hooks": {
+    "after:tool": [
+      {
+        "match": "fs.write",
+        "command": "npx prettier --write {{path}}",
+        "blocking": false
+      }
+    ],
+    "before:plan": [
+      {
+        "command": "./scripts/validate-env.sh",
+        "blocking": true
+      }
+    ]
+  }
+}
+```
+
+#### Available Events
+
+| Event | When |
+|-------|------|
+| `before:tool` / `after:tool` | Before/after any tool executes |
+| `before:plan` / `after:plan` | Before/after a plan runs |
+| `after:step` | After each plan step |
+| `before:skill` / `after:skill` | Around skill execution |
+| `after:decompose` | After goal decomposition |
+| `session:start` / `session:end` | At session boundaries |
+
+```bash
+agent hooks list             # Show registered hooks
+agent hooks add after:tool "npx eslint --fix {{path}}" --match fs.write
+agent hooks events           # Show all available events
+```
+
+---
+
+### 6. Plugins
+
+Bundle skills, commands, and hooks into a distributable package:
+
+```
+my-plugin/
+├── plugin.json
+├── skills/
+│   └── security-scan/
+│       ├── skill.json
+│       └── prompt.md
+├── commands/
+│   └── audit.md
+└── hooks/
+    └── hooks.json
+```
+
+`plugin.json`:
+```json
+{
+  "name": "enterprise-security",
+  "version": "1.0.0",
+  "description": "Security scanning and compliance",
+  "skills": ["skills/"],
+  "commands": ["commands/"],
+  "hooks": "hooks/hooks.json"
+}
+```
+
+```bash
+agent plugins install ./my-plugin    # Install from local path
+agent plugins list                   # Show installed plugins
+agent plugins remove my-plugin       # Uninstall
+```
+
+---
+
+### 7. Multi-CLI Orchestration
+
+The agent can delegate tasks to external AI CLIs when they're the right tool for the job:
+
+| Tool | CLI | Best For |
+|------|-----|----------|
+| `cli.cursor` | Cursor | Multi-file refactoring with codebase context |
+| `cli.codex` | OpenAI Codex | Code generation with sandbox execution |
+| `cli.gemini` | Gemini | Large-context analysis and reasoning |
+| `cli.claude` | Claude | Careful code review and generation |
+
+Configure in `.agent/config.json`:
+```json
+{
+  "cliTools": {
+    "cursor": { "binary": "cursor", "available": true },
+    "claude": { "binary": "claude", "available": true }
+  }
+}
+```
+
+The LLM orchestrator automatically selects the right CLI based on the task.
+
+---
+
+### 8. Goal Management & Daemon
+
+For long-running, multi-step projects:
+
+```bash
+# Create a goal
+agent goal add "Build authentication with OAuth2" --priority 1
+
+# AI decomposes into tasks
+agent goal decompose 1
+
+# Run tasks autonomously
+agent daemon start
+
+# Monitor progress
+agent goal list               # See goal status
+agent goal status 1           # Detailed task view
+agent daemon status           # Daemon health
+agent daemon logs             # Recent execution logs
+
+# Get reports
+agent report generate --summary
+```
+
+---
+
+### 9. Plans
+
+Create and run structured execution plans:
+
+```bash
+agent plan propose "Migrate database from MySQL to PostgreSQL"
+agent plan list
+agent plan run <plan-file>
+```
+
+---
+
+### 10. Memory
+
+The agent stores facts, learnings, and project context persistently:
+
+```bash
+agent memory search "database credentials"
+agent memory add "Staging server is at 10.0.0.5" --category fact
+```
+
+---
+
+## 🤖 Full CLI Reference
+
+### Core
 
-### Goal Management
-| Command | Description |
-|---|---|
-| `agent goal add "<title>"` | Create a new high-level goal |
-| `agent goal list` | List all active goals |
-| `agent goal decompose <id>` | AI-power breakdown of a goal into tasks |
-| `agent goal status <id>` | View tasks and progress for a goal |
-| `agent goal task <id> "<title>"` | Manually add a task to a goal |
-| `agent goal run` | Manually run pending tasks (if daemon is off) |
-
-### Daemon (Background Service)
 | Command | Description |
-|---|---|
-| `agent daemon start` | Start the background worker |
-| `agent daemon stop` | Stop the background worker |
-| `agent daemon status` | View daemon health and uptime |
-| `agent daemon logs` | View recent execution logs |
+|---------|-------------|
+| `agent` | Launch interactive REPL (no subcommand) |
+| `agent run "<goal>"` | One-shot goal execution |
+| `agent init` | Initialize project configuration |
+| `agent config --init` | Set up global config |
+| `agent doctor` | System health check |
 
 ### Skills
+
 | Command | Description |
-|---|---|
+|---------|-------------|
 | `agent skills list` | List installed skills |
 | `agent skills search <query>` | Search the skill hub |
-| `agent skills install <name>` | Install a skill from hub or path |
+| `agent skills install <name>` | Install a skill |
+| `agent skills create <name>` | Create a custom skill |
 | `agent skills stats` | View performance metrics |
 | `agent skills doctor <name>` | Diagnose a failing skill |
-| `agent skills fix <name>` | Auto-fix a broken skill |
+| `agent skills fix <name>` | Auto-repair with LLM |
+
+### Commands
 
-### Reports
 | Command | Description |
-|---|---|
-| `agent report generate` | Generate today's activity report |
-| `agent report generate --summary` | Generate an AI executive summary |
+|---------|-------------|
+| `agent commands list` | List available commands |
 
----
+### Hooks
+
+| Command | Description |
+|---------|-------------|
+| `agent hooks list` | Show registered hooks |
+| `agent hooks add <event> <cmd>` | Add a new hook |
+| `agent hooks events` | Show all hook events |
+
+### Plugins
 
-## 🛠️ Architecture
+| Command | Description |
+|---------|-------------|
+| `agent plugins list` | List installed plugins |
+| `agent plugins install <path>` | Install from local path |
+| `agent plugins remove <name>` | Remove a plugin |
+
+### Goals & Daemon
 
-The runtime consists of several modular components:
+| Command | Description |
+|---------|-------------|
+| `agent goal add "<title>"` | Create a goal |
+| `agent goal list` | List goals |
+| `agent goal decompose <id>` | AI breakdown |
+| `agent goal status <id>` | Task-level progress |
+| `agent daemon start` | Start background worker |
+| `agent daemon stop` | Stop background worker |
+| `agent daemon status` | Health & uptime |
 
-1.  **Orchestrator (CLI)**: Entry point for user interaction.
-2.  **Goal Manager**: State machine for tracking objectives (`Active`, `Completed`, `Failed`).
-3.  **Planner (Decomposer)**: LLM-based engine that breaks goals into dependency-aware tasks.
-4.  **Executor**: The engine that runs tasks. It matches tasks to skills and executes them securely.
-5.  **Memory Store**: Semantic storage using SQLite vector/FTS.
-6.  **Auto-Fixer Loop**: A meta-level process that monitors execution metrics and patches skills that drift or break.
+### Plans, Memory & Reports
+
+| Command | Description |
+|---------|-------------|
+| `agent plan propose "<desc>"` | AI-generate a plan |
+| `agent plan run <file>` | Execute a plan |
+| `agent memory search <query>` | Search agent memory |
+| `agent memory add "<fact>"` | Store a fact |
+| `agent report generate` | Activity report |
 
 ---
 
+## 🏗️ Architecture
 
-## 📚 Learning Series
+```
+┌─────────────────────────────────────────────────────┐
+│                    CLI / REPL                        │
+│  agent run │ agent (REPL) │ /slash-commands │ MCP   │
+├─────────────────────────────────────────────────────┤
+│                  LLM Router                          │
+│  OpenAI │ Anthropic │ Azure │ Ollama (fallback)     │
+├──────────┬──────────┬──────────┬────────────────────┤
+│  Skills  │ Commands │  Hooks   │    Plugins          │
+│  .md     │  .md     │  .json   │    bundles          │
+├──────────┴──────────┴──────────┴────────────────────┤
+│              Tool Registry & Policy Engine           │
+│  fs.* │ cmd.run │ git.* │ cli.* │ project.detect    │
+├─────────────────────────────────────────────────────┤
+│  Planner  │ Executor │ Memory  │ Daemon │ Reporter  │
+└─────────────────────────────────────────────────────┘
+```
 
-Want to understand how this agent works under the hood? Check out our 5-part architecture series:
+**Key Components:**
+- **CLI / REPL**: Entry point—interactive or subcommand-based
+- **LLM Router**: Multi-provider with offline-first support and fallback chains
+- **Skills**: Markdown prompt-based capabilities
+- **Commands**: Lightweight goal templates (YAML frontmatter + prompt)
+- **Hooks**: Event-driven lifecycle interception
+- **Plugins**: Distributable bundles of skills + commands + hooks
+- **Tool Registry**: Sandboxed tool execution with permission gates
+- **Policy Engine**: Human-in-the-loop approval for sensitive operations
+- **Multi-CLI Tools**: Cursor, Codex, Gemini, Claude wrappers
 
-1.  [**Vision & Architecture**](docs/articles/01-vision-architecture.md) - The high-level design.
-2.  [**The Brain (Planner)**](docs/articles/02-goal-decomposition.md) - How goal decomposition works.
-3.  [**The Body (Executor)**](docs/articles/03-skill-execution.md) - Secure skill execution.
-4.  [**Memory & Context**](docs/articles/04-memory-persistence.md) - SQLite & Vector storage.
-5.  [**Self-Improvement**](docs/articles/05-self-improvement.md) - Metrics & The Auto-Fixer.
+---
+
+## 📚 Learning Series
 
-## 🔮 What's Next?
+Understand the agent architecture with our 7-part deep-dive:
 
-We are just getting started. The future includes **Multi-Agent Swarms**, **Sandboxed Execution**, and **Voice Interfaces**.
-Check out our detailed [**ROADMAP.md**](ROADMAP.md) to see where we are heading and how you can help build the future of autonomous software development.
+1. [**Vision & Architecture**](docs/articles/01-vision-architecture.md) — The high-level design
+2. [**The Brain (Planner)**](docs/articles/02-goal-decomposition.md) — Goal decomposition
+3. [**The Body (Executor)**](docs/articles/03-skill-execution.md) — Secure skill execution
+4. [**Memory & Context**](docs/articles/04-memory-persistence.md) — SQLite & semantic search
+5. [**Self-Improvement**](docs/articles/05-self-improvement.md) — Metrics & the Auto-Fixer
+6. [**Plugin Ecosystem**](docs/articles/06-plugin-ecosystem.md) — Hooks, commands, multi-CLI
+7. [**Interactive CLI**](docs/articles/07-interactive-cli.md) — The conversational experience
 
 ### Comparisons
-- [**vs OpenClaw**](docs/comparisons/openclaw.md) - How we differ from other AI OS projects.
+- [**vs OpenClaw**](docs/comparisons/openclaw.md) — How we differ from AI OS projects
+
+---
+
+## 🔮 Roadmap
+
+Check out our detailed [**ROADMAP.md**](ROADMAP.md) to see what's next:
+- ✅ **Phase 5**: Plugin Ecosystem & Extensibility
+- ✅ **Phase 6**: Interactive CLI Experience
+- 🔜 **Phase 1**: Sandboxed Execution & Secrets Management
+- 🔜 **Phase 2**: Multi-Agent Collaboration (The Swarm)
+- 🔜 **Phase 3**: Voice & Vision Interfaces
+- 🔜 **Phase 4**: The Agent Cloud (Skill Hub, Remote Execution, Dashboard)
+
+---
 
 ## 🤝 Contributing
 
-We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to set up your development environment.
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+Key areas where we need help:
+- Writing new Skills
+- Improving Planner prompt engineering
+- Building the Web Dashboard
+- Creating community Plugins
+
+---
 
 ## License
 

package/docs/articles/01-vision-architecture.md

@@ -7,8 +7,9 @@ This is the promise of **Autonomous Agents**. Unlike chatbots, agents have:
 2.  **Memory** (persistence across sessions)
 3.  **Skills** (integrations with real-world tools)
 4.  **Autonomy** (looping execution without constant prompts)
+5.  **Extensibility** (plugins, hooks, and commands to grow capabilities)
 
-In this 5-part series, we will break down exactly how we built `@praveencs/agent`, a powerful, open-source autonomous agent runtime.
+In this 7-part series, we will break down exactly how we built `@praveencs/agent`, a powerful, open-source autonomous agent runtime.
 
 ## 🏗️ The Core Architecture
 
@@ -33,6 +34,16 @@ A developer who forgets the codebase every morning is useless. Our agent needs *
 The secret sauce is the loop. A chatbot waits for input. An agent runs in a loop.
 - **Role**: A background process that constantly checks for pending tasks, file changes, or new goals.
 
+### 5. The Nervous System (Hooks & Plugins)
+As of **v0.8.0**, our agent has a full extensibility layer:
+- **Lifecycle Hooks**: Intercept execution at any point (`before:tool`, `after:plan`, etc.).
+- **Lightweight Commands**: Markdown-based goal templates—no code needed.
+- **Plugin System**: Install community bundles that add skills, commands, and hooks.
+- **Multi-CLI Tools**: Delegate tasks to Cursor, Codex, Gemini, or Claude CLIs.
+
+### 6. The Voice (Interactive CLI)
+The agent now has a **conversational interface**. Type `agent` with no arguments to enter an interactive REPL with slash commands, tab completion, and multi-turn context.
+
 ## 🛠️ Tech Stack
 
 We're building this in **TypeScript** (Node.js) because:
@@ -49,4 +60,13 @@ We're building this in **TypeScript** (Node.js) because:
 
 In **Part 2**, we will dive into the code for **The Brain**. We'll write the `GoalDecomposer` class that turns vague requests into structured project plans.
 
+### 📚 Full Series
+1. **Architecture & Vision** (This Article)
+2. **The Brain (Goal Decomposition)**
+3. **The Body (Skill Execution)**
+4. **The Memory (Persistence)**
+5. **Self-Improvement (Auto-Fixer)**
+6. **Plugin Ecosystem (Hooks, Commands, Multi-CLI)**
+7. **Interactive CLI**
+
 Stay tuned!

package/docs/articles/05-self-improvement.md

@@ -66,15 +66,12 @@ The LLM reads the errors ("not a git repository") and decides to add a check:
 ### 3. Apply & Reload
 The agent overwrites `prompt.md` with the new version and reloads the skill instantly. The next execution uses the fixed logic.
 
-## 🚀 Conclusion
+## 🚀 But Wait, There's More
 
-We have built a system that:
-1.  **Decomposes** vague goals into tasks.
-2.  **Executes** tasks using defined skills.
-3.  **Remembers** context and learnings.
-4.  **Monitors** itself and **Fixes** its own tools.
+In **v0.8.0**, we took everything further. The agent is now extensible and conversational.
 
-This loop—Plan, Do, Check, Act—is the foundation of autonomy.
+In **Part 6**, we'll cover the **Plugin Ecosystem**—hooks that intercept execution, lightweight commands, and multi-CLI orchestration.
+In **Part 7**, we'll build the **Interactive CLI**—a Claude Code-style conversational experience.
 
 ### 📚 Series Recap
 
@@ -83,6 +80,8 @@ This loop—Plan, Do, Check, Act—is the foundation of autonomy.
 - **Part 3**: The Body (Skill Execution)
 - **Part 4**: The Memory (Persistence)
 - **Part 5**: Self-Improvement (Auto-Fixer)
+- **Part 6**: Plugin Ecosystem (Hooks, Commands, Multi-CLI)
+- **Part 7**: Interactive CLI
 
 You can explore the full source code and contribute at [GitHub](https://github.com/praveencs87/agent).
 

package/docs/articles/06-plugin-ecosystem.md

@@ -0,0 +1,195 @@
+# The Plugin Ecosystem: Hooks, Commands & Extensibility (Part 6)
+
+In **Parts 1-5**, we built an agent with a brain, body, memory, and self-healing. But it was a closed system.
+
+In **v0.8.0**, we opened it up. Now anyone can extend the agent with **Plugins**, **Hooks**, and **Commands**—without touching core code.
+
+## 🪝 Lifecycle Hooks
+
+Hooks let you inject custom logic at every execution point. Think of them as Git hooks, but for your agent.
+
+### The Events
+
+| Event | When it fires |
+|-------|--------------|
+| `before:tool` | Before any tool executes |
+| `after:tool` | After any tool completes |
+| `before:plan` | Before a plan starts |
+| `after:step` | After each plan step |
+| `after:plan` | After a plan finishes |
+| `before:skill` / `after:skill` | Around skill execution |
+| `after:decompose` | After goal decomposition |
+| `session:start` / `session:end` | At session boundaries |
+
+### Example: Auto-Format on Write
+
+Create `.agent/hooks/hooks.json`:
+```json
+{
+  "hooks": {
+    "after:tool": [
+      {
+        "match": "fs.write",
+        "command": "npx prettier --write {{path}}",
+        "blocking": false
+      }
+    ],
+    "before:plan": [
+      {
+        "command": "./scripts/validate-env.sh",
+        "blocking": true
+      }
+    ]
+  }
+}
+```
+
+Every time the agent writes a file, Prettier auto-formats it. Before every plan runs, your environment is validated.
+
+### Template Variables
+
+Hook commands support `{{name}}`, `{{event}}`, `{{cwd}}`, `{{path}}`, and `{{runId}}` placeholders. Environment variables like `AGENT_HOOK_EVENT` are also injected.
+
+### CLI
+
+```bash
+agent hooks list              # Show all registered hooks
+agent hooks add after:tool "npx prettier --write {{path}}" --match fs.write
+agent hooks events            # Reference for all available events
+```
+
+---
+
+## ⚡ Lightweight Commands
+
+Skills require a `skill.json`, an entrypoint, and permission declarations. But sometimes you just want a quick recipe.
+
+**Commands** are markdown files with YAML frontmatter. No boilerplate.
+
+### Example: `deploy-staging.md`
+
+Create `.agent/commands/deploy-staging.md`:
+```markdown
+---
+name: deploy-staging
+description: Deploy current branch to staging
+tools: [cmd.run, git.status, git.diff]
+---
+# Deploy to Staging
+
+You are deploying the current branch to staging.
+
+Steps:
+1. Run `npm test` to verify all tests pass
+2. Run `npm run build` to create the production bundle
+3. Run `git push origin HEAD:staging` to trigger deployment
+4. Verify the deployment succeeded
+```
+
+### How It Works
+
+When you run `agent run deploy-staging` or type `/deploy-staging` in interactive mode:
+1. The runtime checks: Is there a **Skill** named `deploy-staging`? → No.
+2. Is there a **Command** named `deploy-staging`? → **Yes!**
+3. The command's markdown body becomes the LLM system prompt.
+4. Only the whitelisted tools (`cmd.run`, `git.status`, `git.diff`) are available.
+
+This gives you **scoped, repeatable tasks without any code**.
+
+### CLI
+
+```bash
+agent commands list           # Show all available commands
+agent run deploy-staging      # Run a command
+agent run /deploy-staging     # Explicit slash-command syntax
+```
+
+---
+
+## 🔧 Multi-CLI Orchestration
+
+Sometimes, the best tool for a job isn't our agent—it's Cursor, Codex, or Claude CLI.
+
+In v0.8.0, we added **first-class AI CLI wrappers** as tools. The LLM orchestrator can delegate sub-tasks to specialized CLIs:
+
+| Tool | Wraps | Best For |
+|------|-------|----------|
+| `cli.cursor` | Cursor CLI | Multi-file refactoring with codebase context |
+| `cli.codex` | OpenAI Codex | Code generation with sandbox execution |
+| `cli.gemini` | Gemini CLI | Large-context analysis and reasoning |
+| `cli.claude` | Claude CLI | Careful code review and generation |
+
+### How It Works
+
+These are standard `ToolDefinition` registrations—the LLM sees them alongside `fs.read`, `cmd.run`, and `git.diff`. When the task requires deep codebase understanding or parallel execution, the LLM can choose:
+
+```
+User: "Refactor the auth module to use JWT"
+Agent LLM: "This needs multi-file refactoring with deep context."
+→ Calls cli.cursor({ prompt: "Refactor auth to JWT...", files: ["src/auth/**"] })
+→ Cursor CLI executes with native codebase indexing
+→ Result returned to our agent for verification
+```
+
+Configure availability in `agent.config.json`:
+```json
+{
+  "cliTools": {
+    "cursor": { "binary": "cursor", "available": true },
+    "claude": { "binary": "claude", "available": true }
+  }
+}
+```
+
+---
+
+## 🔌 The Plugin System
+
+A **Plugin** bundles skills, commands, hooks, and tools into a single installable package.
+
+### Plugin Structure
+
+```
+my-plugin/
+├── .agent-plugin/
+│   └── plugin.json          # Manifest
+├── skills/
+│   └── security-scan/
+│       ├── skill.json
+│       └── prompt.md
+├── commands/
+│   └── audit.md
+└── hooks/
+    └── hooks.json
+```
+
+### Manifest (`plugin.json`)
+
+```json
+{
+  "name": "enterprise-security",
+  "version": "1.0.0",
+  "description": "Security scanning and compliance",
+  "skills": ["skills/"],
+  "commands": ["commands/"],
+  "hooks": "hooks/hooks.json"
+}
+```
+
+### CLI
+
+```bash
+agent plugins install ./my-plugin    # Install from local path
+agent plugins list                   # Show installed plugins
+agent plugins remove my-plugin      # Uninstall
+```
+
+When a plugin is installed, its skills, commands, and hooks are automatically loaded on every `agent` run.
+
+---
+
+## 🚀 What's Next?
+
+The plugin ecosystem opens the door to community contributions. Imagine installing `agent plugins install security-scanner` and instantly getting OWASP scanning as a hook on every build.
+
+In **Part 7**, we'll cover the new **Interactive CLI**—the Claude Code-style conversational experience.

package/docs/articles/07-interactive-cli.md

@@ -0,0 +1,172 @@
+# The Interactive CLI: A Claude Code-Style Experience (Part 7)
+
+In **Part 6**, we gave the agent extensibility. In **Part 7**, we give it a personality.
+
+Most CLI tools are fire-and-forget: you type a command, get output, done. But modern AI agents deserve a **conversational interface**—one where you stay in a flow, the agent remembers context, and you can guide it naturally.
+
+## 🤖 The REPL
+
+When you type `agent` with no subcommand, you enter **Interactive Mode**:
+
+```
+$ agent
+
+  ╭────────────────────────────────────────────────╮
+  │  🤖 Agent Runtime v0.8.0                       │
+  │    Project: my-app                              │
+  │    Model: gpt-4o │ 3 skills │ 2 commands        │
+  ╰────────────────────────────────────────────────╯
+
+  Type a goal, a /command, or /help for help.
+
+  > Add input validation to the signup form
+  ⠋ Thinking...
+  ⚡ fs.read(src/pages/signup.tsx) ✓
+  ⚡ fs.write(src/pages/signup.tsx) ✓
+  ⚡ cmd.run(npm test) ✓
+
+  Added Zod validation schema for email and password fields.
+  Tests pass.
+
+  ────────────────────────────────────────────────────────
+  ✓ Done (8.2s)
+
+  > Now add rate limiting to the API endpoint
+  ⠋ Thinking...
+```
+
+Notice the second prompt: **the agent remembers** the first task. It knows you're working on the signup form and can connect the two requests.
+
+## 🔑 Key Features
+
+### 1. Multi-Turn Conversation
+
+Unlike `agent run "do X"` (which is one-shot), the REPL maintains conversation history across turns. The `ConversationManager` (`src/cli/conversation.ts`) tracks all messages:
+
+```typescript
+conversation.addUser("Add validation");
+// → LLM sees full history including previous turns
+const messages = conversation.getMessages();
+```
+
+When context gets too long, use `/compact` to summarize and trim:
+```
+  > /compact
+  Conversation compacted. Context freed.
+```
+
+### 2. Slash Commands
+
+Type `/` to access built-in commands:
+
+| Command | What it does |
+|---------|-------------|
+| `/help` | Show all available commands |
+| `/skills` | List installed skills with status |
+| `/commands` | List available lightweight commands |
+| `/hooks` | Show registered lifecycle hooks |
+| `/model` | Display current model and providers |
+| `/compact` | Summarize and trim conversation context |
+| `/clear` | Clear the terminal screen |
+| `/exit` | Exit interactive mode |
+
+Your custom `.agent/commands/*.md` files are also available as slash commands! If you have `deploy-staging.md`, you can type `/deploy-staging`.
+
+### 3. Tab Completion
+
+Press `Tab` after `/` to see all available slash commands. The REPL uses readline's `completer` for instant autocompletion:
+
+```
+  > /sk<TAB>
+  > /skills
+```
+
+### 4. Inline Tool Execution
+
+When the agent calls tools, you see them in real-time with status badges:
+
+```
+  ⚡ fs.read(src/auth/handler.ts) ✓         # Success
+  ⚡ cmd.run(npm test) ✗ Test failed        # Failure with reason
+  ⚡ cli.cursor(refactor auth...) ✓          # Delegated to external CLI
+```
+
+### 5. Rich Welcome Banner
+
+The bordered banner shows at-a-glance info:
+- Current project name (from `package.json`)
+- Active LLM model
+- Number of loaded skills and commands
+
+## 🏗️ Architecture
+
+```
+bin/agent.ts
+  └── No subcommand?
+      └── startREPL() ← src/cli/repl.ts
+          ├── Bootstrap (config, tools, skills, commands, hooks)
+          ├── renderBanner()
+          └── readline loop
+              ├── /slash-command → SlashCommandRegistry
+              ├── /user-command → CommandLoader → LLM loop (scoped tools)
+              └── natural language → ConversationManager → LLM loop (all tools)
+```
+
+All existing subcommands (`agent run`, `agent plan`, `agent skills`) continue to work exactly as before. The REPL is an *additional* entry point, not a replacement.
+
+## 💻 Implementation Highlights
+
+### Spinner Integration
+
+We use `ora` for smooth loading states:
+```typescript
+const spinner = new Spinner();
+spinner.start('Thinking...');
+// ... LLM call ...
+spinner.stop();
+```
+
+### Tool Call Display
+
+The `renderToolCall` function shows tool execution inline:
+```typescript
+renderToolCall('fs.read', { path: 'src/app.ts' }, 'running');
+// Output: ⚡ fs.read({"path":"src/app.ts"})
+// Then on completion:
+renderToolCall('fs.read', args, 'success');
+// Output: ✓
+```
+
+### Backward Compatibility
+
+The entry point (`bin/agent.ts`) detects whether a subcommand was provided:
+```typescript
+const hasSubcommand = args.length > 0 && !args[0].startsWith('-');
+if (hasSubcommand) {
+    program.parse(process.argv);  // Traditional CLI
+} else {
+    startREPL();  // Interactive mode
+}
+```
+
+## 🚀 What's Next?
+
+The interactive CLI opens up new possibilities:
+- **Streaming responses** — Show LLM output character-by-character
+- **Checkpointing** — Rewind codebase to a previous state within a session
+- **Project Memory** — Automatic `.agent.md` files for project-specific context
+- **Multi-agent mode** — Spawn sub-agents for parallel tasks within the REPL
+
+---
+
+### 📚 Full Series
+
+1. **Architecture & Vision**
+2. **The Brain (Goal Decomposition)**
+3. **The Body (Skill Execution)**
+4. **The Memory (Persistence)**
+5. **Self-Improvement (Auto-Fixer)**
+6. **Plugin Ecosystem (Hooks, Commands, Multi-CLI)**
+7. **Interactive CLI (This Article)**
+
+Explore the source code at [GitHub](https://github.com/praveencs87/agent) or install with `npm i -g @praveencs/agent`.

package/docs/comparisons/openclaw.md

@@ -1,21 +1,23 @@
 # Comparison: @praveencs/agent vs OpenClaw
 
-This document compares `@praveencs/agent` (this project) with [OpenClaw](https://github.com/openclaw/openclaw), a popular open-source AI operating system.
+This document compares `@praveencs/agent` v0.8.0 (this project) with [OpenClaw](https://github.com/openclaw/openclaw), a popular open-source AI operating system.
 
 ## 1. Core Philosophy
 
 | Feature | @praveencs/agent | OpenClaw |
 |---|---|---|
 | **Primary Goal** | **Autonomous Task Execution.** Designed to be a headless "digital employee" that plans and builds software in the background. | **AI Operating System.** Designed to be a "24/7 Jarvis" that integrates with chat apps (Discord, Telegram) and manages your digital life. |
-| **Interaction** | **CLI-First.** You give it a goal, and it works silently. | **Chat-First.** You talk to it via various messaging platforms. |
+| **Interaction** | **CLI-First + Interactive REPL.** Subcommands for automation, plus a conversational mode with slash commands. | **Chat-First.** You talk to it via various messaging platforms. |
 | **Persona** | A Junior Developer / Project Manager. | A Personal Assistant / OS Interface. |
 
 ## 2. Architecture
 
 ### @praveencs/agent
 - **Monolithic CLI/Daemon**: A single TypeScript application that runs locally.
+- **Interactive REPL**: Conversational mode with multi-turn context (v0.8.0).
 - **Daemon Loop**: A background process that polls a queue of tasks.
 - **Planner-Executor Split**: Explicit "Brain" (Goal Decomposition) and "Body" (Task Execution) separation.
+- **Plugin System**: Extensible via hooks, commands, and plugin bundles (v0.8.0).
 - **Database**: Uses `better-sqlite3` for high-performance, structured local storage.
 
 ### OpenClaw
@@ -27,11 +29,22 @@ This document compares `@praveencs/agent` (this project) with [OpenClaw](https:/
 
 | | @praveencs/agent | OpenClaw |
 |---|---|---|
-| **Skill Definition** | **Prompt-as-Code.** Skills are simple `.md` files with natural language instructions. | **Plugin System.** Code-based plugins to extend functionality. |
-| **Execution** | **Shell-Native.** Executes command-line tools natively (git, docker, npm). | **Sandbox-Native.** Heavily focuses on browser automation and secure sandboxing. |
+| **Skill Definition** | **Prompt-as-Code.** Skills are `.md` files + Commands are lightweight goal templates. | **Plugin System.** Code-based plugins to extend functionality. |
+| **Execution** | **Shell-Native + Multi-CLI.** Executes command-line tools natively AND delegates to Cursor/Codex/Gemini/Claude CLIs. | **Sandbox-Native.** Heavily focuses on browser automation and secure sandboxing. |
+| **Extensibility** | **Hooks + Plugins.** Lifecycle hooks at every execution point, distributable plugin bundles. | **Plugin-based.** Extends via code plugins. |
 | **Self-Improvement** | **Built-in Auto-Fixer.** Monitors success rates and rewrites broken skills automatically. | **Manual/Plugin.** Relies on users or plugin updates. |
 
-## 4. Memory Implementation
+## 4. CLI Experience
+
+| | @praveencs/agent v0.8.0 | OpenClaw |
+|---|---|---|
+| **Interactive Mode** | ✅ Conversational REPL with multi-turn context | ❌ Chat-app dependent |
+| **Slash Commands** | ✅ `/help`, `/skills`, `/commands`, `/hooks`, `/model`, custom user commands | N/A |
+| **Tab Completion** | ✅ Built-in autocomplete | N/A |
+| **Lifecycle Hooks** | ✅ 10 event types with template variables | ❌ |
+| **Multi-CLI Orchestration** | ✅ Cursor, Codex, Gemini, Claude wrappers | ❌ |
+
+## 5. Memory Implementation
 
 ### @praveencs/agent
 - **Hybrid Storage**: Uses **SQLite** for structured data (tasks, metrics) and **Vector/FTS5** layers for semantic search.
@@ -41,11 +54,13 @@ This document compares `@praveencs/agent` (this project) with [OpenClaw](https:/
 - **File-System Storage**: Stores conversations and memories as Markdown files.
 - **Why?**: "Unix philosophy" - easy to read/edit by humans, no database dependencies.
 
-## 5. Use Case Recommendation
+## 6. Use Case Recommendation
 
 **Choose @praveencs/agent if:**
 - You want an AI to **write code, manage servers, or automate dev workflows**.
-- You prefer a command-line interface.
+- You want an **interactive conversational CLI** experience.
+- You need a **plugin ecosystem** to extend capabilities.
+- You want to **orchestrate multiple AI CLIs** (Cursor, Claude, etc.).
 - You need structured planning and long-term project management.
 - You want a system that improves itself over time.
 
@@ -57,4 +72,4 @@ This document compares `@praveencs/agent` (this project) with [OpenClaw](https:/
 
 ## Summary
 
-While OpenClaw builds a bridge between AI and *Communication Channels*, `@praveencs/agent` builds a bridge between AI and *Work Execution*. We are focused on the "Agent as a Worker" paradigm, whereas OpenClaw focuses on "Agent as an Interface".
+While OpenClaw builds a bridge between AI and *Communication Channels*, `@praveencs/agent` builds a bridge between AI and *Work Execution*. With v0.8.0, we've added extensibility (plugins, hooks, commands) and a modern interactive CLI, making it the most developer-centric autonomous agent available.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@praveencs/agent",
-    "version": "0.8.0",
+    "version": "0.8.2",
     "files": [
         "dist",
         "bin",