@praveencs/agent 0.8.1 โ†’ 0.8.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +428 -131
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,17 +1,51 @@
1
- # Agent Runtime
1
+ # ๐Ÿค– Agent Runtime
2
2
 
3
- 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.
3
+ > An autonomous, goal-oriented AI agent runtime with an interactive CLI, plugin ecosystem, and self-improvement capabilities.
4
4
 
5
- ---
5
+ [![npm version](https://img.shields.io/npm/v/@praveencs/agent)](https://www.npmjs.com/package/@praveencs/agent)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
7
+
8
+ ```
9
+ $ agent
10
+
11
+ โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
12
+ โ”‚ ๐Ÿค– Agent Runtime v0.8.1 โ”‚
13
+ โ”‚ Project: my-app โ”‚
14
+ โ”‚ Model: gpt-4o โ”‚ 3 skills โ”‚ 2 commands โ”‚
15
+ โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ
16
+
17
+ Type a goal, a /command, or /help for help.
6
18
 
7
- ## ๐Ÿš€ Features
19
+ > Refactor the auth module to use JWT
20
+ โ ‹ Thinking...
21
+ โšก fs.read(src/auth/handler.ts) โœ“
22
+ โšก fs.write(src/auth/jwt.ts) โœ“
23
+ โšก cmd.run(npm test) โœ“
8
24
 
9
- - **๐Ÿง  Goal Decomposition**: Uses LLM reasoning to break complex, high-level objectives into specific, actionable tasks.
10
- - **โšก Autonomous Execution**: Runs tasks in the background via a robust daemon process, respecting dependencies and priorities.
11
- - **๐Ÿ’พ Persistent Memory**: SQLite-based semantic memory with FTS5 search. Stores facts, project context, and learned patterns across sessions.
12
- - **๐Ÿ› ๏ธ Extensible Skill System**: Capabilities are defined by simple markdown prompts (`prompt.md`). Install skills from a hub or create your own.
13
- - **๐Ÿ“Š Reporting**: Generates daily standup reports and executive summaries of activity and progress.
14
- - **โค๏ธ Self-Improvement**: Tracks skill performance metrics and automatically attempts to patch/repair failing skills using the LLM.
25
+ โœ“ Done (12.3s)
26
+
27
+ > /deploy-staging
28
+ Running command: deploy-staging...
29
+ ```
30
+
31
+ ---
32
+
33
+ ## โœจ Features
34
+
35
+ | Category | Capabilities |
36
+ |----------|-------------|
37
+ | **๐Ÿค– Interactive CLI** | Conversational REPL with multi-turn context, slash commands, and tab completion |
38
+ | **๐Ÿง  Goal Decomposition** | LLM-powered breakdown of complex objectives into dependency-aware task graphs |
39
+ | **โšก Autonomous Execution** | Background daemon processes tasks with retries, rollback, and verification |
40
+ | **๐Ÿ› ๏ธ Extensible Skills** | Markdown-based skill definitionsโ€”install from a hub or write your own |
41
+ | **โšก Lightweight Commands** | Quick goal templates as markdown filesโ€”no boilerplate needed |
42
+ | **๐Ÿช Lifecycle Hooks** | Intercept execution at 10 event points (before:tool, after:plan, etc.) |
43
+ | **๐Ÿ”Œ Plugin System** | Bundle skills, commands, and hooks into distributable packages |
44
+ | **๐Ÿ”ง Multi-CLI Orchestration** | Delegate tasks to Cursor, Codex, Gemini, or Claude CLIs |
45
+ | **๐Ÿ’พ Persistent Memory** | SQLite + FTS5 semantic memory across sessions |
46
+ | **โค๏ธ Self-Improvement** | Monitors skill metrics and auto-patches failing skills |
47
+ | **๐Ÿ“Š Reporting** | Daily standup reports and AI-generated executive summaries |
48
+ | **๐Ÿ”’ Policy Engine** | Permission-gated tool execution with human-in-the-loop approval |
15
49
 
16
50
  ---
17
51
 
@@ -21,181 +55,444 @@ An autonomous, goal-oriented AI agent runtime with persistent memory, skill exec
21
55
  npm install -g @praveencs/agent
22
56
  ```
23
57
 
24
- ### Initial Configuration
25
- After installation, initialize the configuration:
58
+ ### Quick Start
59
+
60
+ ```bash
61
+ # Initialize project configuration
62
+ agent init
63
+
64
+ # Launch interactive mode (recommended)
65
+ agent
66
+
67
+ # Or run a one-off goal
68
+ agent run "Add input validation to the signup form"
69
+ ```
70
+
71
+ ### Configuration
72
+
73
+ After `agent init`, a `.agent/` directory is created in your project with configuration, skills, commands, and hooks. Set your LLM provider API keys:
26
74
 
27
75
  ```bash
76
+ # Set via environment variables
77
+ export OPENAI_API_KEY=sk-...
78
+ export ANTHROPIC_API_KEY=sk-ant-...
79
+
80
+ # Or configure directly
28
81
  agent config --init
29
82
  ```
30
83
 
31
- 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.
84
+ ---
85
+
86
+ ## ๐Ÿ“– Usage Guide
87
+
88
+ ### 1. Interactive Mode (Recommended)
89
+
90
+ Type `agent` with no arguments to enter the **Interactive REPL**:
91
+
92
+ ```bash
93
+ agent
94
+ ```
95
+
96
+ You get a bordered welcome banner showing your project, model, and loaded extensions. Then just type naturally:
97
+
98
+ ```
99
+ > Add rate limiting to the /api/auth endpoint
100
+ > Now write tests for it
101
+ > /deploy-staging
102
+ ```
103
+
104
+ The agent **remembers context** across turnsโ€”no need to repeat yourself.
105
+
106
+ #### Slash Commands
107
+
108
+ | Command | Action |
109
+ |---------|--------|
110
+ | `/help` | Show all available commands |
111
+ | `/skills` | List installed skills with status |
112
+ | `/commands` | List available lightweight commands |
113
+ | `/hooks` | Show registered lifecycle hooks |
114
+ | `/model` | Display current model and provider info |
115
+ | `/compact` | Summarize conversation and free context |
116
+ | `/clear` | Clear the terminal screen |
117
+ | `/exit` | Exit interactive mode |
118
+
119
+ Custom commands from `.agent/commands/` are also available as slash commands (e.g., `/deploy-staging`).
120
+
121
+ **Tab completion** works on all slash commandsโ€”press `Tab` after `/`.
32
122
 
33
123
  ---
34
124
 
35
- ## ๐Ÿ“– User Guide
125
+ ### 2. One-Shot Mode
36
126
 
37
- ### 1. The Workflow
38
- The typical workflow follows a **Plan โ†’ Decompose โ†’ Execute โ†’ Report** cycle:
127
+ Run a single goal without entering the REPL:
39
128
 
40
- 1. **Plan**: Tell the agent what you want to achieve.
41
- ```bash
42
- agent goal add "Create a personal blog with Next.js and PostgreSQL" --priority 1
43
- # Output: Goal #1 created
44
- ```
129
+ ```bash
130
+ agent run "Refactor the database module to use connection pooling"
131
+ agent run "Fix all TypeScript errors in the project"
132
+ agent run deploy-staging # Runs a named Command or Skill
133
+ ```
45
134
 
46
- 2. **Decompose**: Ask the agent to break it down.
47
- ```bash
48
- agent goal decompose 1
49
- # Output: Goal decomposed into 5 tasks (Scaffold, DB Setup, Styling...)
50
- ```
51
- *The agent uses its LLM planner to analyze the goal and your available skills to create a task list.*
135
+ ---
52
136
 
53
- 3. **Execute**: Start the daemon to work on tasks autonomously.
54
- ```bash
55
- agent daemon start
56
- ```
57
- *The daemon runs in the background, processing tasks, handling retries, and logging activity.*
137
+ ### 3. Skills
58
138
 
59
- You can check progress at any time:
60
- ```bash
61
- agent goal list # See goal status
62
- agent goal status 1 # See detailed task status for Goal #1
63
- agent daemon status # Check if the worker is running
64
- ```
139
+ Skills are reusable capabilities defined by markdown prompts and a `skill.json` manifest.
65
140
 
66
- 4. **Report**: Get a summary of what happened.
67
- ```bash
68
- agent report generate --summary
69
- ```
70
- *Generates a notification-style summary of completed work, new learnings, and any blockers.*
141
+ ```bash
142
+ # List installed skills
143
+ agent skills list
71
144
 
72
- ### 2. Managing Skills
73
- Skills are the tools your agent uses (e.g., `git-commit`, `docker-deploy`, `file-write`).
145
+ # Search the skill hub
146
+ agent skills search "docker"
74
147
 
75
- - **List installed skills**:
76
- ```bash
77
- agent skills list
78
- ```
148
+ # Install a skill
149
+ agent skills install <skill-name>
79
150
 
80
- - **Find new skills**:
81
- ```bash
82
- agent skills search "database"
83
- agent skills browse
84
- ```
151
+ # Create a custom skill
152
+ agent skills create my-new-skill
153
+ # โ†’ Creates .agent/skills/my-new-skill/prompt.md
85
154
 
86
- - **Install a skill**:
87
- ```bash
88
- agent skills install <skill-name>
89
- ```
155
+ # Self-healing
156
+ agent skills stats # View success rates
157
+ agent skills doctor my-skill # Diagnose failures
158
+ agent skills fix my-skill # Auto-repair with LLM
159
+ ```
90
160
 
91
- - **Create a custom skill**:
92
- ```bash
93
- agent skills create my-new-skill
94
- ```
95
- *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.*
161
+ ---
96
162
 
97
- - **Self-Repair (Doctor)**:
98
- If a skill is failing, the agent can diagnose and fix it.
99
- ```bash
100
- agent skills stats # View success rates
101
- agent skills doctor my-skill # Analyze error logs
102
- agent skills fix my-skill # Attempt AI auto-repair
103
- ```
163
+ ### 4. Lightweight Commands
104
164
 
105
- ### 3. Memory & Context
106
- The agent automatically saves important information (like "Project uses Tailwind CSS") to its memory. You can search or manage this manually.
165
+ Commands are quick goal templatesโ€”just a markdown file. No `skill.json` needed.
107
166
 
108
- - **Search memory**:
109
- ```bash
110
- agent memory search "database credentials"
111
- ```
112
- - **Add a fact**:
113
- ```bash
114
- agent memory add "The staging server IP is 10.0.0.5" --category fact
115
- ```
167
+ Create `.agent/commands/deploy-staging.md`:
116
168
 
169
+ ```markdown
117
170
  ---
171
+ name: deploy-staging
172
+ description: Deploy current branch to staging
173
+ tools: [cmd.run, git.status, git.diff]
174
+ ---
175
+ # Deploy to Staging
118
176
 
119
- ## ๐Ÿค– CLI Command Reference
177
+ Steps:
178
+ 1. Run `npm test` to verify all tests pass
179
+ 2. Run `npm run build` to create the production bundle
180
+ 3. Run `git push origin HEAD:staging` to trigger deployment
181
+ ```
120
182
 
121
- ### General
122
- | Command | Description |
123
- |Str |---|
124
- | `agent run "<instruction>"` | Run a one-off instruction immediately |
125
- | `agent config --init` | Initialize configuration |
126
- | `agent doctor` | Check system health (dependencies, config) |
183
+ Now use it:
184
+
185
+ ```bash
186
+ agent run deploy-staging # From CLI
187
+ # or
188
+ > /deploy-staging # From interactive mode
189
+ ```
190
+
191
+ The command's markdown body becomes the LLM prompt, and only the whitelisted tools are available.
192
+
193
+ ```bash
194
+ agent commands list # See all available commands
195
+ ```
196
+
197
+ ---
198
+
199
+ ### 5. Lifecycle Hooks
200
+
201
+ Hooks intercept agent execution at every point. Define them in `.agent/hooks/hooks.json`:
202
+
203
+ ```json
204
+ {
205
+ "hooks": {
206
+ "after:tool": [
207
+ {
208
+ "match": "fs.write",
209
+ "command": "npx prettier --write {{path}}",
210
+ "blocking": false
211
+ }
212
+ ],
213
+ "before:plan": [
214
+ {
215
+ "command": "./scripts/validate-env.sh",
216
+ "blocking": true
217
+ }
218
+ ]
219
+ }
220
+ }
221
+ ```
222
+
223
+ #### Available Events
224
+
225
+ | Event | When |
226
+ |-------|------|
227
+ | `before:tool` / `after:tool` | Before/after any tool executes |
228
+ | `before:plan` / `after:plan` | Before/after a plan runs |
229
+ | `after:step` | After each plan step |
230
+ | `before:skill` / `after:skill` | Around skill execution |
231
+ | `after:decompose` | After goal decomposition |
232
+ | `session:start` / `session:end` | At session boundaries |
233
+
234
+ ```bash
235
+ agent hooks list # Show registered hooks
236
+ agent hooks add after:tool "npx eslint --fix {{path}}" --match fs.write
237
+ agent hooks events # Show all available events
238
+ ```
239
+
240
+ ---
241
+
242
+ ### 6. Plugins
243
+
244
+ Bundle skills, commands, and hooks into a distributable package:
245
+
246
+ ```
247
+ my-plugin/
248
+ โ”œโ”€โ”€ plugin.json
249
+ โ”œโ”€โ”€ skills/
250
+ โ”‚ โ””โ”€โ”€ security-scan/
251
+ โ”‚ โ”œโ”€โ”€ skill.json
252
+ โ”‚ โ””โ”€โ”€ prompt.md
253
+ โ”œโ”€โ”€ commands/
254
+ โ”‚ โ””โ”€โ”€ audit.md
255
+ โ””โ”€โ”€ hooks/
256
+ โ””โ”€โ”€ hooks.json
257
+ ```
258
+
259
+ `plugin.json`:
260
+ ```json
261
+ {
262
+ "name": "enterprise-security",
263
+ "version": "1.0.0",
264
+ "description": "Security scanning and compliance",
265
+ "skills": ["skills/"],
266
+ "commands": ["commands/"],
267
+ "hooks": "hooks/hooks.json"
268
+ }
269
+ ```
270
+
271
+ ```bash
272
+ agent plugins install ./my-plugin # Install from local path
273
+ agent plugins list # Show installed plugins
274
+ agent plugins remove my-plugin # Uninstall
275
+ ```
276
+
277
+ ---
278
+
279
+ ### 7. Multi-CLI Orchestration
280
+
281
+ The agent can delegate tasks to external AI CLIs when they're the right tool for the job:
282
+
283
+ | Tool | CLI | Best For |
284
+ |------|-----|----------|
285
+ | `cli.cursor` | Cursor | Multi-file refactoring with codebase context |
286
+ | `cli.codex` | OpenAI Codex | Code generation with sandbox execution |
287
+ | `cli.gemini` | Gemini | Large-context analysis and reasoning |
288
+ | `cli.claude` | Claude | Careful code review and generation |
289
+
290
+ Configure in `.agent/config.json`:
291
+ ```json
292
+ {
293
+ "cliTools": {
294
+ "cursor": { "binary": "cursor", "available": true },
295
+ "claude": { "binary": "claude", "available": true }
296
+ }
297
+ }
298
+ ```
299
+
300
+ The LLM orchestrator automatically selects the right CLI based on the task.
301
+
302
+ ---
303
+
304
+ ### 8. Goal Management & Daemon
305
+
306
+ For long-running, multi-step projects:
307
+
308
+ ```bash
309
+ # Create a goal
310
+ agent goal add "Build authentication with OAuth2" --priority 1
311
+
312
+ # AI decomposes into tasks
313
+ agent goal decompose 1
314
+
315
+ # Run tasks autonomously
316
+ agent daemon start
317
+
318
+ # Monitor progress
319
+ agent goal list # See goal status
320
+ agent goal status 1 # Detailed task view
321
+ agent daemon status # Daemon health
322
+ agent daemon logs # Recent execution logs
323
+
324
+ # Get reports
325
+ agent report generate --summary
326
+ ```
327
+
328
+ ---
329
+
330
+ ### 9. Plans
331
+
332
+ Create and run structured execution plans:
333
+
334
+ ```bash
335
+ agent plan propose "Migrate database from MySQL to PostgreSQL"
336
+ agent plan list
337
+ agent plan run <plan-file>
338
+ ```
339
+
340
+ ---
341
+
342
+ ### 10. Memory
343
+
344
+ The agent stores facts, learnings, and project context persistently:
345
+
346
+ ```bash
347
+ agent memory search "database credentials"
348
+ agent memory add "Staging server is at 10.0.0.5" --category fact
349
+ ```
350
+
351
+ ---
352
+
353
+ ## ๐Ÿค– Full CLI Reference
354
+
355
+ ### Core
127
356
 
128
- ### Goal Management
129
- | Command | Description |
130
- |---|---|
131
- | `agent goal add "<title>"` | Create a new high-level goal |
132
- | `agent goal list` | List all active goals |
133
- | `agent goal decompose <id>` | AI-power breakdown of a goal into tasks |
134
- | `agent goal status <id>` | View tasks and progress for a goal |
135
- | `agent goal task <id> "<title>"` | Manually add a task to a goal |
136
- | `agent goal run` | Manually run pending tasks (if daemon is off) |
137
-
138
- ### Daemon (Background Service)
139
357
  | Command | Description |
140
- |---|---|
141
- | `agent daemon start` | Start the background worker |
142
- | `agent daemon stop` | Stop the background worker |
143
- | `agent daemon status` | View daemon health and uptime |
144
- | `agent daemon logs` | View recent execution logs |
358
+ |---------|-------------|
359
+ | `agent` | Launch interactive REPL (no subcommand) |
360
+ | `agent run "<goal>"` | One-shot goal execution |
361
+ | `agent init` | Initialize project configuration |
362
+ | `agent config --init` | Set up global config |
363
+ | `agent doctor` | System health check |
145
364
 
146
365
  ### Skills
366
+
147
367
  | Command | Description |
148
- |---|---|
368
+ |---------|-------------|
149
369
  | `agent skills list` | List installed skills |
150
370
  | `agent skills search <query>` | Search the skill hub |
151
- | `agent skills install <name>` | Install a skill from hub or path |
371
+ | `agent skills install <name>` | Install a skill |
372
+ | `agent skills create <name>` | Create a custom skill |
152
373
  | `agent skills stats` | View performance metrics |
153
374
  | `agent skills doctor <name>` | Diagnose a failing skill |
154
- | `agent skills fix <name>` | Auto-fix a broken skill |
375
+ | `agent skills fix <name>` | Auto-repair with LLM |
376
+
377
+ ### Commands
155
378
 
156
- ### Reports
157
379
  | Command | Description |
158
- |---|---|
159
- | `agent report generate` | Generate today's activity report |
160
- | `agent report generate --summary` | Generate an AI executive summary |
380
+ |---------|-------------|
381
+ | `agent commands list` | List available commands |
161
382
 
162
- ---
383
+ ### Hooks
384
+
385
+ | Command | Description |
386
+ |---------|-------------|
387
+ | `agent hooks list` | Show registered hooks |
388
+ | `agent hooks add <event> <cmd>` | Add a new hook |
389
+ | `agent hooks events` | Show all hook events |
390
+
391
+ ### Plugins
163
392
 
164
- ## ๐Ÿ› ๏ธ Architecture
393
+ | Command | Description |
394
+ |---------|-------------|
395
+ | `agent plugins list` | List installed plugins |
396
+ | `agent plugins install <path>` | Install from local path |
397
+ | `agent plugins remove <name>` | Remove a plugin |
398
+
399
+ ### Goals & Daemon
165
400
 
166
- The runtime consists of several modular components:
401
+ | Command | Description |
402
+ |---------|-------------|
403
+ | `agent goal add "<title>"` | Create a goal |
404
+ | `agent goal list` | List goals |
405
+ | `agent goal decompose <id>` | AI breakdown |
406
+ | `agent goal status <id>` | Task-level progress |
407
+ | `agent daemon start` | Start background worker |
408
+ | `agent daemon stop` | Stop background worker |
409
+ | `agent daemon status` | Health & uptime |
167
410
 
168
- 1. **Orchestrator (CLI)**: Entry point for user interaction.
169
- 2. **Goal Manager**: State machine for tracking objectives (`Active`, `Completed`, `Failed`).
170
- 3. **Planner (Decomposer)**: LLM-based engine that breaks goals into dependency-aware tasks.
171
- 4. **Executor**: The engine that runs tasks. It matches tasks to skills and executes them securely.
172
- 5. **Memory Store**: Semantic storage using SQLite vector/FTS.
173
- 6. **Auto-Fixer Loop**: A meta-level process that monitors execution metrics and patches skills that drift or break.
411
+ ### Plans, Memory & Reports
412
+
413
+ | Command | Description |
414
+ |---------|-------------|
415
+ | `agent plan propose "<desc>"` | AI-generate a plan |
416
+ | `agent plan run <file>` | Execute a plan |
417
+ | `agent memory search <query>` | Search agent memory |
418
+ | `agent memory add "<fact>"` | Store a fact |
419
+ | `agent report generate` | Activity report |
174
420
 
175
421
  ---
176
422
 
423
+ ## ๐Ÿ—๏ธ Architecture
177
424
 
178
- ## ๐Ÿ“š Learning Series
425
+ ```
426
+ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
427
+ โ”‚ CLI / REPL โ”‚
428
+ โ”‚ agent run โ”‚ agent (REPL) โ”‚ /slash-commands โ”‚ MCP โ”‚
429
+ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
430
+ โ”‚ LLM Router โ”‚
431
+ โ”‚ OpenAI โ”‚ Anthropic โ”‚ Azure โ”‚ Ollama (fallback) โ”‚
432
+ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
433
+ โ”‚ Skills โ”‚ Commands โ”‚ Hooks โ”‚ Plugins โ”‚
434
+ โ”‚ .md โ”‚ .md โ”‚ .json โ”‚ bundles โ”‚
435
+ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
436
+ โ”‚ Tool Registry & Policy Engine โ”‚
437
+ โ”‚ fs.* โ”‚ cmd.run โ”‚ git.* โ”‚ cli.* โ”‚ project.detect โ”‚
438
+ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
439
+ โ”‚ Planner โ”‚ Executor โ”‚ Memory โ”‚ Daemon โ”‚ Reporter โ”‚
440
+ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
441
+ ```
179
442
 
180
- Want to understand how this agent works under the hood? Check out our 5-part architecture series:
443
+ **Key Components:**
444
+ - **CLI / REPL**: Entry pointโ€”interactive or subcommand-based
445
+ - **LLM Router**: Multi-provider with offline-first support and fallback chains
446
+ - **Skills**: Markdown prompt-based capabilities
447
+ - **Commands**: Lightweight goal templates (YAML frontmatter + prompt)
448
+ - **Hooks**: Event-driven lifecycle interception
449
+ - **Plugins**: Distributable bundles of skills + commands + hooks
450
+ - **Tool Registry**: Sandboxed tool execution with permission gates
451
+ - **Policy Engine**: Human-in-the-loop approval for sensitive operations
452
+ - **Multi-CLI Tools**: Cursor, Codex, Gemini, Claude wrappers
181
453
 
182
- 1. [**Vision & Architecture**](docs/articles/01-vision-architecture.md) - The high-level design.
183
- 2. [**The Brain (Planner)**](docs/articles/02-goal-decomposition.md) - How goal decomposition works.
184
- 3. [**The Body (Executor)**](docs/articles/03-skill-execution.md) - Secure skill execution.
185
- 4. [**Memory & Context**](docs/articles/04-memory-persistence.md) - SQLite & Vector storage.
186
- 5. [**Self-Improvement**](docs/articles/05-self-improvement.md) - Metrics & The Auto-Fixer.
454
+ ---
455
+
456
+ ## ๐Ÿ“š Learning Series
187
457
 
188
- ## ๐Ÿ”ฎ What's Next?
458
+ Understand the agent architecture with our 7-part deep-dive:
189
459
 
190
- We are just getting started. The future includes **Multi-Agent Swarms**, **Sandboxed Execution**, and **Voice Interfaces**.
191
- 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.
460
+ 1. [**Vision & Architecture**](docs/articles/01-vision-architecture.md) โ€” The high-level design
461
+ 2. [**The Brain (Planner)**](docs/articles/02-goal-decomposition.md) โ€” Goal decomposition
462
+ 3. [**The Body (Executor)**](docs/articles/03-skill-execution.md) โ€” Secure skill execution
463
+ 4. [**Memory & Context**](docs/articles/04-memory-persistence.md) โ€” SQLite & semantic search
464
+ 5. [**Self-Improvement**](docs/articles/05-self-improvement.md) โ€” Metrics & the Auto-Fixer
465
+ 6. [**Plugin Ecosystem**](docs/articles/06-plugin-ecosystem.md) โ€” Hooks, commands, multi-CLI
466
+ 7. [**Interactive CLI**](docs/articles/07-interactive-cli.md) โ€” The conversational experience
192
467
 
193
468
  ### Comparisons
194
- - [**vs OpenClaw**](docs/comparisons/openclaw.md) - How we differ from other AI OS projects.
469
+ - [**vs OpenClaw**](docs/comparisons/openclaw.md) โ€” How we differ from AI OS projects
470
+
471
+ ---
472
+
473
+ ## ๐Ÿ”ฎ Roadmap
474
+
475
+ Check out our detailed [**ROADMAP.md**](ROADMAP.md) to see what's next:
476
+ - โœ… **Phase 5**: Plugin Ecosystem & Extensibility
477
+ - โœ… **Phase 6**: Interactive CLI Experience
478
+ - ๐Ÿ”œ **Phase 1**: Sandboxed Execution & Secrets Management
479
+ - ๐Ÿ”œ **Phase 2**: Multi-Agent Collaboration (The Swarm)
480
+ - ๐Ÿ”œ **Phase 3**: Voice & Vision Interfaces
481
+ - ๐Ÿ”œ **Phase 4**: The Agent Cloud (Skill Hub, Remote Execution, Dashboard)
482
+
483
+ ---
195
484
 
196
485
  ## ๐Ÿค Contributing
197
486
 
198
- We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to set up your development environment.
487
+ We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
488
+
489
+ Key areas where we need help:
490
+ - Writing new Skills
491
+ - Improving Planner prompt engineering
492
+ - Building the Web Dashboard
493
+ - Creating community Plugins
494
+
495
+ ---
199
496
 
200
497
  ## License
201
498
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@praveencs/agent",
3
- "version": "0.8.1",
3
+ "version": "0.8.2",
4
4
  "files": [
5
5
  "dist",
6
6
  "bin",