@praveencs/agent 0.7.0 → 0.7.2

package/README.md

@@ -1,67 +1,183 @@
 # Agent Runtime
 
-An autonomous, goal-oriented AI agent runtime with persistent memory, skill execution, and self-improvement capabilities.
+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.
 
-## Features
+---
 
-- **🧠 Goal Decomposition**: Breaks high-level objectives into actionable tasks using LLM reasoning.
-- **⚡ Autonomous Execution**: Runs tasks in the background via a daemon process.
-- **💾 Persistent Memory**: SQLite-based memory store with FTS5 search for context retention.
-- **🛠️ Skill System**: Extensible toolset defined by simple markdown prompts.
-- **📊 Reporting**: Generates daily activity reports and executive summaries.
-- **❤️ Self-Improvement**: Tracks skill performance and automatically patches broken skills.
+## 🚀 Features
 
-## Quick Start
+- **🧠 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.
+
+---
+
+## 📦 Installation
 
 ```bash
-# 1. Install & Configure
 npm install -g @praveencs/agent
+```
+
+### Initial Configuration
+After installation, initialize the configuration:
+
+```bash
 agent config --init
+```
 
-# 2. Add a Goal
-agent goal add "Create a personal blog with Next.js" --priority 1
+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.
+
+---
+
+## 📖 User Guide
+
+### 1. The Workflow
+The typical workflow follows a **Plan → Decompose → Execute → Report** cycle:
+
+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
+    ```
+
+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.*
+
+    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
+    ```
+
+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.*
+
+### 2. Managing Skills
+Skills are the tools your agent uses (e.g., `git-commit`, `docker-deploy`, `file-write`).
+
+- **List installed skills**:
+  ```bash
+  agent skills list
+  ```
+
+- **Find new skills**:
+  ```bash
+  agent skills search "database"
+  agent skills browse
+  ```
+
+- **Install a skill**:
+  ```bash
+  agent skills install <skill-name>
+  ```
+
+- **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
+  ```
+
+### 3. Memory & Context
+The agent automatically saves important information (like "Project uses Tailwind CSS") to its memory. You can search or manage this manually.
+
+- **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
+  ```
+
+---
+
+## 🤖 CLI Command Reference
+
+### 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) |
+
+### 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 |
 
-# 3. Decompose & Plan
-agent goal decompose 1
+### 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 stats` | View performance metrics |
+| `agent skills doctor <name>` | Diagnose a failing skill |
+| `agent skills fix <name>` | Auto-fix a broken skill |
 
-# 4. Start Autonomous Mode
-agent daemon start
+### Reports
+| Command | Description |
+|---|---|
+| `agent report generate` | Generate today's activity report |
+| `agent report generate --summary` | Generate an AI executive summary |
 
-# View status
-agent daemon status
-agent goal list
-```
+---
 
-## Core Concepts
+## 🛠️ Architecture
 
-### Goals & Tasks
-Goals are high-level objectives. The agent breaks them down into atomic **Tasks**.
-Each task can be executed by a specific **Skill** or by general LLM reasoning.
+The runtime consists of several modular components:
 
-### Skills
-Skills are the agent's tools. They are defined in `prompt.md` files.
-- `agent skills list` - View installed skills
-- `agent skills create <name>` - Create a new skill
-- `agent skills doctor <name>` - Diagnose issues
-- `agent skills fix <name>` - Auto-repair a broken skill
+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.
 
-### Memory
-The agent remembers what it learns.
-- `agent memory search "context"` - Search the knowledge base
-- `agent report generate` - View daily activity
+---
 
-## Architecture
+## 🤝 Contributing
 
-- **`src/daemon`**: Background service manager.
-- **`src/goals`**: Planning and execution engine.
-- **`src/memory`**: SQLite storage layer.
-- **`src/skills`**: Skill loader and auto-fixer.
-- **`src/llm`**: Multi-provider LLM router.
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to set up your development environment.
 
-## Development
+## License
 
-```bash
-npm install
-npm run build
-npm test
-```
+MIT

package/dist/src/cli/index.js

@@ -18,7 +18,7 @@ export function createCLI() {
     program
         .name('agent')
         .description('Agent Runtime — autonomous, goal-oriented AI agent with skills, plans, memory, and permissioned tools')
-        .version('0.7.0')
+        .version('0.7.2')
         .option('--verbose', 'Enable verbose output')
         .option('--no-color', 'Disable colored output')
         .option('--config <path>', 'Path to config file');

package/package.json

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