@mndrk/agx 1.4.8 → 1.4.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mndrk/agx",
-  "version": "1.4.8",
+  "version": "1.4.9",
   "description": "Unified AI Agent Wrapper for Gemini, Claude, and Ollama",
   "main": "index.js",
   "bin": {

package/skills/agx/SKILL.md

@@ -1,69 +1,130 @@
-# agx - Autonomous AI Agents
+# agx - Task Orchestrator for Autonomous AI Agents
 
-Run AI agents that work autonomously until done. One command starts everything.
+Run AI agents that work autonomously across sessions. Uses `mem` for persistent memory.
 
-## Autonomous Mode
+## Core Concept: Wake-Work-Sleep Cycle
+
+Agents have NO memory between sessions. All continuity comes from `mem`:
+
+```
+WAKE → Load state from mem → WORK → Save state to mem → SLEEP → repeat
+```
+
+## Quick Start
 
 ```bash
+# Create and run a task
+agx new "Build a REST API with auth"
+agx run build-rest-api
+
+# Or one command for autonomous mode
 agx -a -p "Build a REST API with auth"
-# ✓ Created task: build-rest-api  
-# ✓ Daemon started (wakes every 15m)
-# ✓ Working...
 ```
 
-The agent continues working automatically until `[done]` or `[blocked]`.
+## Task Management
 
-## One-Shot Mode
+```bash
+agx new "<goal>"        # Create task
+agx run [task]          # Run task (loads context, wakes agent)
+agx tasks               # List all tasks
+agx status              # Current task status
+agx context [task]      # View task context
+agx pause [task]        # Pause task
+agx remove [task]       # Remove task
+```
+
+## Steering: Nudge a Task
 
-For quick questions without persistence:
+Send guidance to an agent for its next wake cycle:
 
 ```bash
-agx -p "explain this code"
-agx claude -p "fix this bug" -y
+agx nudge <task> "focus on auth first"    # Add nudge
+agx nudge <task>                          # View pending nudges
 ```
 
-## Output Markers
+Nudges are shown to the agent on wake and then cleared.
+
+## Memory Commands (via mem)
 
-Use these in your output to control state:
+Agents use these to persist state:
+
+### Define Objective
+```bash
+mem goal "<objective>"        # Set/update goal
+mem criteria add "<text>"     # Add success criterion
+mem constraint add "<rule>"   # Add boundary/constraint
+```
 
-### Progress (parsed automatically)
+### Track Progress
+```bash
+mem next "<step>"             # Set what you're working on
+mem checkpoint "<msg>"        # Save progress point
+mem criteria <n>              # Mark criterion #n complete
+mem progress                  # Check progress %
 ```
-[checkpoint: message]   # Save progress
-[learn: insight]        # Record learning
-[next: step]            # Set next step
-[criteria: N]           # Mark criterion #N complete
+
+### Learn & Adapt
+```bash
+mem learn "<insight>"         # Task-specific learning
+mem learn -g "<insight>"      # Global learning (all tasks)
+mem stuck "<reason>"          # Mark blocker
+mem stuck clear               # Clear blocker
 ```
 
-### Stopping Markers
+### Build Playbook
+```bash
+mem learnings -g              # List global learnings
+mem promote <n>               # Promote learning to playbook
+mem playbook                  # View global playbook
 ```
-[done]                  # Task complete, stop
-[blocked: reason]       # Need human help, pause
-[approve: question]     # Need approval first
+
+### Complete
+```bash
+mem done                      # Mark task complete
 ```
 
-**Default:** Keep working. Only use stopping markers when genuinely done or stuck.
+## Agent Workflow
+
+When an agent wakes, it should:
 
-## Checking Tasks
+1. **Orient** - Read state (goal, criteria, progress, next step)
+2. **Plan** - Define criteria if missing, set intent with `mem next`
+3. **Execute** - Work toward criteria, save learnings
+4. **Checkpoint** - Save progress with `mem checkpoint`
+5. **Adapt** - Handle blockers or ask user for nudge
+
+## Daemon Mode
+
+Run tasks on a schedule:
 
 ```bash
-agx status          # Current task
-agx tasks           # All tasks
-agx progress        # % complete
-agx daemon logs     # Recent activity
+agx daemon start              # Start daemon
+agx daemon stop               # Stop daemon
+agx daemon status             # Check status
+agx daemon logs               # View logs
 ```
 
 ## Providers
 
-| Provider | Alias |
-|----------|-------|
-| claude | c |
-| gemini | g |
-| ollama | o |
+```bash
+agx claude [args]             # Claude (alias: c)
+agx gemini [args]             # Gemini (alias: g)
+agx ollama [args]             # Ollama (alias: o)
+```
 
 ## Key Flags
 
 ```bash
--a, --autonomous    # Full auto mode (task + daemon + work until done)
+-a, --autonomous    # Full auto: create task + daemon + work until done
 -p, --prompt        # The prompt/goal
--y, --yolo          # Skip confirmations (implied by -a)
+-y, --yolo          # Skip confirmations
+--continue <task>   # Continue specific task
 ```
+
+## Key Principles
+
+- **Memory is everything** - Agents forget between sessions. Save state.
+- **Criteria drive completion** - No criteria = no way to know when done.
+- **Checkpoint often** - Sessions can die anytime.
+- **Ask when stuck** - Get a nudge from the user vs. spinning.
+- **Learn & promote** - Build the playbook for future tasks.