@nicolasmondain/cli-agent 2.1.1 → 2.1.2

package/README.md

@@ -1,8 +1,8 @@
 # cli-agent
 
-> Bridge the gap between natural language and CLI commands
+> A semantic command catalog for AI agents
 
-A CLI wrapper that enables AI agents to discover and execute commands through a semantic catalog. Define your commands once in JSON, and let both humans and AI agents use them seamlessly.
+A CLI wrapper that enables AI agents to discover and execute commands through a structured catalog. Define your commands once in JSON, and let both humans and AI agents use them seamlessly.
 
 ## Why cli-agent?
 
@@ -16,45 +16,48 @@ AI agents can execute scripts, but they face challenges:
 
 ### The Solution
 
-cli-agent provides a **semantic catalog** of commands that enables AI agents to understand and orchestrate multiple commands from a single natural language request:
+cli-agent provides a **semantic catalog** of commands. AI agents read the catalog, match commands to user intent, and execute them one by one:
 
 ```mermaid
 flowchart TD
-    A["User: 'Set up my project with linting and tests'"] --> B[".cli-agent.json\nSemantic Catalog"]
+    A["User: 'Set up my project with linting and tests'"] --> B[AI Agent]
     B --> C["cli-agent list --format json"]
-    C --> D["Agent identifies matching commands"]
-    D --> E["cli-agent init my-project --format json"]
-    D --> F["cli-agent add-linting --format json"]
-    D --> G["cli-agent add-testing --format json"]
-    E --> H["Structured JSON output"]
-    F --> H
-    G --> H
-    H --> I["Agent reports combined results"]
+    C --> D["Agent reads command catalog"]
+    D --> E["Agent matches intent to commands"]
+    E --> F["cli-agent init my-project --format json"]
+    F --> G{Success?}
+    G -->|Yes| H["cli-agent add-linting --format json"]
+    G -->|No| I["Agent stops and reports error"]
+    H --> J{Success?}
+    J -->|Yes| K["cli-agent add-testing --format json"]
+    J -->|No| I
+    K --> L["Agent reports combined results"]
 ```
 
 ## How It Works
 
-When you say: **"Set up my project with linting and tests"**
+When an AI agent (like Claude) receives: **"Set up my project with linting and tests"**
 
-The AI agent:
-
-1. Reads `.cli-agent.json` (or runs `cli-agent list --format json`)
-2. Matches command descriptions to your intent:
+1. **Discovery**: The agent calls `cli-agent list --format json` to get the command catalog
+2. **Matching**: The agent reads command descriptions and matches them to user intent:
    - `init` → "Initialize a new project with standard structure"
    - `add-linting` → "Add ESLint configuration to the project"
    - `add-testing` → "Add Jest/Vitest testing setup"
-3. Executes each command sequentially:
+3. **Execution**: The agent executes each command one by one:
    ```bash
    cli-agent init my-project --format json
    cli-agent add-linting --format json
    cli-agent add-testing --format json
    ```
-4. Parses each JSON response and reports combined results
+4. **Error handling**: If any command fails, the agent stops the sequence and reports the error
+5. **Result**: The agent aggregates results and reports back to the user
+
+**Note:** cli-agent itself has no AI capabilities. It's a tool catalog and executor. The AI agent (Claude, GPT, etc.) handles the natural language understanding and orchestration.
 
 ## Features
 
-- **Natural Language Mapping** — Command descriptions enable AI agents to match user intent to the right command
-- **Command Discovery** — `cli-agent list --format json` exposes all commands with their arguments and options
+- **Semantic Catalog** — Command descriptions enable AI agents to match user intent
+- **Command Discovery** — `cli-agent list --format json` exposes all commands with arguments and options
 - **MCP Integration** — Generate MCP tool manifests for native Claude Code integration
 - **Multi-runtime Support** — Execute JavaScript, TypeScript, and shell scripts
 - **AI-First Design** — JSON output, non-interactive execution, predictable exit codes
@@ -275,7 +278,7 @@ cli-agent looks for configuration in this order:
 
 ### Writing Effective Descriptions
 
-Good descriptions are crucial for AI agents to match user intent:
+Good descriptions help AI agents match user intent to the right command:
 
 ```json
 {
@@ -386,12 +389,12 @@ All commands automatically have these options:
 
 ## Multi-Command Orchestration
 
-cli-agent is designed to be called multiple times by an AI agent. The agent orchestrates the execution flow based on user intent:
+cli-agent is designed to be called multiple times by an AI agent. The **agent** orchestrates the execution flow based on user intent:
 
 ```mermaid
 sequenceDiagram
     participant User
-    participant Agent
+    participant Agent as AI Agent
     participant CLI as cli-agent
     
     User->>Agent: "Set up my project with linting and tests"
@@ -399,19 +402,19 @@ sequenceDiagram
     CLI-->>Agent: Command catalog (JSON)
     Agent->>Agent: Match intent to commands
     Agent->>CLI: cli-agent init my-project --format json
-    CLI-->>Agent: {"success": true, "data": {...}}
+    CLI-->>Agent: {"success": true, ...}
     Agent->>CLI: cli-agent add-linting --format json
-    CLI-->>Agent: {"success": true, "data": {...}}
+    CLI-->>Agent: {"success": true, ...}
     Agent->>CLI: cli-agent add-testing --format json
-    CLI-->>Agent: {"success": true, "data": {...}}
+    CLI-->>Agent: {"success": true, ...}
     Agent->>User: "Project setup complete with linting and tests"
 ```
 
-The agent decides which commands to run and in what order. cli-agent provides:
-
-- **Discovery**: Machine-readable command catalog
-- **Execution**: Consistent invocation interface
-- **Output**: Structured JSON for reliable parsing
+**Key points:**
+- The AI agent decides which commands to run and in what order
+- cli-agent executes one command per invocation
+- If a command fails, the agent can stop the sequence
+- cli-agent provides discovery, execution, and structured output
 
 ## Using Utilities in Scripts
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nicolasmondain/cli-agent",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "Generic CLI wrapper for executing external scripts, designed for both human developers and AI agents (MCP compatible)",
   "type": "module",
   "main": "./dist/index.js",