openstoat 0.2.1 → 0.2.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 +39 -146
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -4,196 +4,89 @@
4
4
 
5
5
  [![npm version](https://img.shields.io/npm/v/openstoat.svg)](https://www.npmjs.com/package/openstoat)
6
6
 
7
- OpenStoat is a **decoupled task queue** that coordinates AI agents and humans. AI handles tasks that don't require human input; when humans complete their tasks, downstream AI tasks are triggered automatically. No cloud, no API keys, no built-in LLM — just a local SQLite store and a CLI that both agents and humans use.
8
-
9
7
  ---
10
8
 
11
- ## Features
9
+ ## Who should read what
12
10
 
13
- | Feature | Description |
14
- |---------|-------------|
15
- | **Local-first** | All data in `~/.openstoat/` (SQLite). No account or API key required. |
16
- | **CLI-first** | Every operation via `openstoat` commands. Same CLI for agents and humans. |
17
- | **No LLM** | OpenStoat orchestrates only. Planning and execution are done by external agents (Cursor, Claude, etc.). |
18
- | **1 human + N agents** | Humans are the bottleneck; AI fills idle time. Explicit ownership per task. |
19
- | **Transparent** | Clear task states, dependencies, and handoffs. |
11
+ **This README is written for humans.** If you're a human and want to quickly understand what OpenStoat is and how to use it, read this.
20
12
 
21
- ---
13
+ **`openstoat --help` is written for AI agents.** If you're an AI agent, use `openstoat --help` (and `openstoat manual`) for the full operational guide — task commands, workflows, and rules.
22
14
 
23
- ## Quick Start
15
+ ---
24
16
 
25
- ### Install
17
+ ## What is OpenStoat?
26
18
 
27
- ```bash
28
- npm install -g openstoat
29
- # or
30
- bun add -g openstoat
31
- # or
32
- npx openstoat --help
33
- ```
19
+ OpenStoat is a **decoupled task queue** that coordinates AI agents and humans. AI handles tasks that don't require human input; when humans complete their tasks, downstream AI tasks are triggered automatically. No cloud, no API keys, no built-in LLM — just a local SQLite store and a CLI.
34
20
 
35
- ### 1. Initialize a project
21
+ - **Local-first**: All data in `~/.openstoat/` (SQLite)
22
+ - **1 human + N agents**: Humans are the bottleneck; AI fills idle time
23
+ - **Transparent**: Clear task states, dependencies, and handoffs
36
24
 
37
- ```bash
38
- openstoat project init --id my_project --name "My Project" --template checkout-default-v1
39
- ```
25
+ ---
40
26
 
41
- ### 2. Create tasks
27
+ ## Install
42
28
 
43
29
  ```bash
44
- openstoat task create \
45
- --project my_project \
46
- --title "Implement payment provider mapping" \
47
- --description "Add Paddle to provider enum and implement mapping" \
48
- --acceptance-criteria "Checkout works with Paddle" \
49
- --acceptance-criteria "Unit tests pass" \
50
- --status ready \
51
- --owner agent_worker \
52
- --task-type implementation
30
+ npm install -g openstoat
53
31
  ```
54
32
 
55
- ### 3. Claim and execute (as agent or human)
33
+ ---
56
34
 
57
- ```bash
58
- openstoat task claim task_001 --as agent_worker --logs-append "Claimed"
59
- openstoat task start task_001 --as agent_worker --logs-append "Started"
60
- openstoat task done task_001 \
61
- --output "Implemented and tested" \
62
- --handoff-summary "Added Paddle provider mapping in src/payments/provider-map.ts. No migration needed. Tests pass." \
63
- --logs-append "Completed"
64
- ```
35
+ ## 1. Initialize a project
65
36
 
66
- ### 4. Optional: Web UI
37
+ **How:**
67
38
 
68
39
  ```bash
69
- openstoat web
70
- # Opens http://localhost:3080
40
+ openstoat project init --id my_project --name "My Project" --template checkout-default-v1
71
41
  ```
72
42
 
73
- ### 5. Optional: Daemon for auto-scheduling AI tasks
74
-
75
- ```bash
76
- openstoat daemon init # Configure .openstoat.json
77
- openstoat daemon start # Poll for ready agent_worker tasks and invoke your agent
78
- ```
43
+ **Why:** Every task belongs to a project. You must create a project before agents can create or work on tasks. The project ID (`my_project`) is used in all task commands.
79
44
 
80
45
  ---
81
46
 
82
- ## Core Concepts
83
-
84
- | Concept | Description |
85
- |---------|-------------|
86
- | **Project** | Template-bound workspace. Every task belongs to one project. |
87
- | **Task** | Smallest unit of work. Status: `ready` → `in_progress` → `done`. Owner: `agent_worker` or `human_worker`. |
88
- | **Template** | Workflow template defining which task types need human input (e.g. credentials, review, deploy). |
89
- | **Handoff** | Context passed when a task completes. Required on every `done` (min 200 chars). |
90
- | **Self-unblock** | When an agent is blocked by human input: create a human task, then run `task self-unblock` with `--depends-on`. |
91
-
92
- ---
47
+ ## 2. Install skills in your OpenClaw project
93
48
 
94
- ## CLI Commands
95
-
96
- | Command | Description |
97
- |---------|-------------|
98
- | `openstoat project init` | Initialize project (requires `--id`, `--name`, `--template`) |
99
- | `openstoat project ls` | List projects |
100
- | `openstoat project show <id>` | Show project details |
101
- | `openstoat task ls` | List tasks (filter by `--project`, `--status`, `--owner`) |
102
- | `openstoat task create` | Create task (all required fields) |
103
- | `openstoat task claim <id>` | Claim ready task (`--as agent_worker` or `human_worker`) |
104
- | `openstoat task start <id>` | Start working on task |
105
- | `openstoat task done <id>` | Complete task (`--output`, `--handoff-summary` required) |
106
- | `openstoat task self-unblock <id>` | Rollback when blocked (`--depends-on` human task required) |
107
- | `openstoat task show <id>` | Show task details |
108
- | `openstoat daemon init` | Interactively create `.openstoat.json` |
109
- | `openstoat daemon start` | Start worker daemon (polls for ready agent tasks) |
110
- | `openstoat install skill` | Install planner and worker skills for agents |
111
- | `openstoat web` | Start Web UI server |
112
- | `openstoat manual` | Print full agent operational manual |
113
-
114
- Run `openstoat --help` for full usage.
49
+ **How:** In your OpenClaw project directory (where you run OpenClaw as Agent Planner):
115
50
 
116
- ---
117
-
118
- ## Daemon Configuration
119
-
120
- The daemon polls for `ready` tasks owned by `agent_worker` and invokes your configured agent. Create `.openstoat.json` in your project root:
121
-
122
- ```json
123
- {
124
- "project": "my_project",
125
- "agent": "/path/to/agent-executable",
126
- "agent_args_template": "{{prompt}}"
127
- }
51
+ ```bash
52
+ openstoat install skill --here
128
53
  ```
129
54
 
130
- | Field | Description |
131
- |-------|-------------|
132
- | `project` | Project ID for task commands. |
133
- | `agent` | Path to your agent executable (e.g. Cursor CLI, Claude CLI). |
134
- | `agent_args_template` | Optional. How to pass the prompt. Use `{{prompt}}` as placeholder. Default: `{{prompt}}` (positional). Examples: `--prompt {{prompt}}`, `-m {{prompt}}` for agents that expect different CLI flags. |
135
-
136
- ---
137
-
138
- ## Agent Workflows
139
-
140
- ### Agent Planner
141
-
142
- 1. **Before creating tasks**: List existing tasks to avoid duplicates.
143
- ```bash
144
- openstoat task ls --project <project_id> --status ready,in_progress
145
- ```
146
- 2. **Create tasks**: Use `task create` with `owner=agent_worker` or `owner=human_worker` and `--depends-on` for dependencies.
147
-
148
- ### Agent Worker
55
+ This installs planner and worker skills to the current directory (`./openstoat-planner`, `./openstoat-worker`).
149
56
 
150
- 1. **Claim**: `openstoat task claim <id> --as agent_worker --logs-append "Claimed"`
151
- 2. **Start**: `openstoat task start <id> --as agent_worker --logs-append "Started"`
152
- 3. **Done**: `openstoat task done <id> --output "..." --handoff-summary "..." --logs-append "..."` (handoff min 200 chars)
153
-
154
- ### Agent Blocked by Human
155
-
156
- 1. Create human task: `openstoat task create --project X --owner human_worker --task-type credentials ...`
157
- 2. Self-unblock: `openstoat task self-unblock <my_task_id> --depends-on <human_task_id> --logs-append "Blocked: ..."`
158
- 3. Resume after human completes the dependency.
57
+ **Why:** OpenClaw (or other agents) need these skills to know how to use OpenStoat — creating tasks, claiming, executing, handing off. Without them, the agent won't know the CLI workflow. Use OpenClaw as your Agent Planner because it has memory and timer features that help with planning over time.
159
58
 
160
59
  ---
161
60
 
162
- ## Install Skills for AI Agents
61
+ ## 3. Start the daemon
163
62
 
164
- OpenStoat provides skills for planner and worker roles. Install them so your AI agent (Cursor, Claude, etc.) can use them:
63
+ **How:**
165
64
 
166
65
  ```bash
167
- openstoat install skill
168
- # Installs to .agent/skills and .claude/skills
66
+ openstoat daemon init # First time: interactively create .openstoat.json
67
+ openstoat daemon start # Start the daemon
169
68
  ```
170
69
 
171
- Use `--here` to install to the current directory instead.
172
-
173
- ---
174
-
175
- ## Recommended Setup
176
-
177
- ### Agent Planner
70
+ Run these from your **project source root** (where your code lives and where `.openstoat.json` will be created).
178
71
 
179
- Use **OpenClaw** as your Agent Planner — it has memory and timer features, which help with planning and decomposing work over time.
72
+ **What it does:** The daemon polls for `ready` tasks owned by `agent_worker`. When it finds one, it invokes your configured agent (e.g. Cursor CLI, Claude Code) with the task prompt. The agent then claims the task, implements it, and marks it done. One task per poll; the daemon keeps running.
180
73
 
181
- ### Daemon & Worker Agent
74
+ **Why:** So your coding agents can pick up work automatically without you manually triggering them. Configure the agent path in `.openstoat.json` — recommend Claude Code or Cursor CLI for coding tasks.
182
75
 
183
- Run `openstoat daemon init` in your project source root to create `.openstoat.json`. For the agent executable, you can use:
76
+ ---
184
77
 
185
- - **Claude Code** or **Cursor CLI** (recommended) — both offer membership plans and excel at coding
186
- - OpenCode
187
- - OpenClaw
78
+ ## 4. Start the Web UI
188
79
 
189
- ### Running Multiple Agents in Parallel
80
+ **How:**
190
81
 
191
- If you need several agents working at once, create separate project directories. For example, if your project is `x`, create `x1`, `x2`, `x3` — each agent runs in its own environment with its own daemon config, so they work in parallel without interfering.
82
+ ```bash
83
+ openstoat web
84
+ # Opens http://localhost:3080
85
+ ```
192
86
 
193
- ### Human Workflow
87
+ **Why:** To view the Kanban board and monitor task progress.
194
88
 
195
- - Use `openstoat web` to view the Kanban board and monitor progress.
196
- - **Tip**: Create a dedicated project (e.g. `x0`) for human tasks — your window for manually directing agents. When you finish your work, simply tell the agent in `x0` that you're done and ask it to run `openstoat task done <task_id>` for your task.
89
+ **Recommendation:** For interacting with OpenStoat (e.g. marking your human tasks done), use an **agent in project x0** instead of the web UI. Create a dedicated project `x0` for human tasks. When you finish your work, tell the agent in x0 that you're done and ask it to run `openstoat task done <task_id>` for your task. The agent handles the CLI; you just talk to it.
197
90
 
198
91
  ---
199
92
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "openstoat",
3
- "version": "0.2.1",
3
+ "version": "0.2.2",
4
4
  "description": "AI and Human task queue - orchestrate work between AI agents and humans with a local-first CLI",
5
5
  "bin": {
6
6
  "openstoat": "./bin/openstoat"