@questionbase/deskfree 0.3.0-alpha.36 → 0.3.0-alpha.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@questionbase/deskfree",
-  "version": "0.3.0-alpha.36",
+  "version": "0.3.0-alpha.38",
   "description": "OpenClaw channel plugin for DeskFree — turns DeskFree into a messaging platform for OpenClaw AI agents",
   "type": "module",
   "main": "dist/index.js",
@@ -40,15 +40,15 @@
     "url": "git+https://github.com/questionbase/deskfree.git"
   },
   "peerDependencies": {
-    "openclaw": "2026.2.21"
+    "openclaw": "2026.3.1"
   },
   "devDependencies": {
-    "@sinclair/typebox": "^0.34.0",
-    "@types/ws": "^8.5.0",
+    "@sinclair/typebox": "^0.34.48",
+    "@types/ws": "^8.18.1",
     "tsup": "8.5.1",
-    "typescript": "^5.9.0",
+    "typescript": "^5.9.3",
     "vitest": "^4.0.18",
-    "ws": "^8.18.0"
+    "ws": "^8.19.0"
   },
   "keywords": [
     "openclaw",

package/skills/deskfree/SKILL.md

@@ -4,7 +4,7 @@ description: >
   DeskFree task management and human-AI collaboration workflows.
   Use when: creating tasks, managing work items, updating files,
   communicating with humans through DeskFree, checking workspace state,
-  handling task lifecycle (start → work → complete → review),
+  handling task lifecycle (start → work → ask → complete),
   updating ways of working, managing initiatives.
   Do NOT use for: general project management advice without DeskFree tools,
   OpenClaw configuration or gateway setup, non-DeskFree platforms (Jira, Asana, etc.),
@@ -30,13 +30,13 @@ deskfree_propose → [human approves in modal] → bot → [start_task] → bot
                                                               │
                                                          [approve]
                                                               ↓
-                                                           done → update_knowledge
+                                                           done (with optional learnings + follow-ups)
 ```
 
 - Proposals live as metadata on a single message — **NO database rows until human approves**
 - Human reviews everything in a modal: can edit titles, instructions, toggle skills
-- `complete_task` outcome `done` = work complete (summary required)
-- `complete_task` outcome `blocked` = need human input (send message FIRST explaining why)
+- `complete_task` = task is done. Optionally include learnings (WoW/initiative updates) and follow-up proposals.
+- Use `send_message(type: 'ask')` when you need human input — don't complete, just ask.
 
 ### The Work Loop
 
@@ -47,7 +47,7 @@ deskfree_propose → [human approves in modal] → bot → [start_task] → bot
 4. Load skill      → deskfree_read_skill_section (if skills were attached)
 5. Do the work     → deskfree_update_file
 6. Complete        → deskfree_complete_task
-7. Update knowledge → deskfree_update_knowledge (orchestrator only, after human approves)
+7. Complete task → deskfree_complete_task (marks done, optionally updates WoW/initiative + proposes follow-ups)
 ```
 
 ### Three Rules
@@ -64,7 +64,7 @@ deskfree_propose → [human approves in modal] → bot → [start_task] → bot
 
 **Initiatives** = human aspirations ("where are we going"). Named after outcomes, not activities. Descriptions are 2-3 aspirational sentences — not project plans.
 
-**Ways of Working (WoW)** = learned preferences ("how WE work together"). Evolves from completed tasks via `deskfree_update_knowledge`. Unique to each bot-human relationship.
+**Ways of Working (WoW)** = learned preferences ("how WE work together"). Evolves from completed tasks via the `learnings` param on `deskfree_complete_task`. Unique to each bot-human relationship.
 
 When proposing tasks:
 - Check WoW for established patterns before proposing
@@ -108,7 +108,7 @@ Keep instructions concise. Brief a contractor: what to do, what done looks like.
 
 ## Tools Reference
 
-### Orchestrator Tools (6)
+### Orchestrator Tools (5)
 
 | Tool | What it does |
 |---|---|
@@ -116,10 +116,9 @@ Keep instructions concise. Brief a contractor: what to do, what done looks like.
 | `deskfree_propose` | Propose a plan for human approval — one initiative per call |
 | `deskfree_schedule_task` | Defer or activate a task (pass ISO datetime or null) |
 | `deskfree_reopen_task` | Reopen a completed task back to bot queue |
-| `deskfree_update_knowledge` | Update WoW and/or initiative content after task completion |
 | `deskfree_send_message` | Send a message to the human (1-3 sentences, no walls of text) |
 
-### Worker Tools (7 — sub-agents)
+### Worker Tools (6 — sub-agents)
 
 | Tool | What it does |
 |---|---|
@@ -137,7 +136,7 @@ Keep instructions concise. Brief a contractor: what to do, what done looks like.
 ### Heartbeat / Proactive Check
 
 1. `deskfree_state` → get workspace snapshot
-2. `bot` tasks with no active sub-agent? → spawn sub-agents to claim them
+2. `open` tasks with `awaiting: bot` and no active sub-agent? → spawn sub-agents to claim them
 3. Anything else needing attention? → act on it
 
 ### Human Gives You Work
@@ -159,7 +158,7 @@ Sub-agent:    deskfree_start_task → deskfree_update_file → deskfree_complete
 
 - One task per sub-agent
 - Workers keep messages concise — senior colleague giving a status update, not a report
-- If blocked: send message explaining WHY, then complete with outcome "blocked"
+- If blocked: send an `ask` message explaining what you need. Sub-agent terminates after ask.
 
 ---
 
@@ -168,8 +167,8 @@ Sub-agent:    deskfree_start_task → deskfree_update_file → deskfree_complete
 | Error | Cause | Action |
 |---|---|---|
 | `deskfree_state` returns empty | No tasks exist | Create if appropriate. Do NOT retry in a loop. |
-| 404 on `deskfree_start_task` | Task not available | Call `deskfree_state`, try a different task. |
-| 409 on `deskfree_start_task` | Race condition | Call `deskfree_state`, pick a different task. |
+| 404 on `deskfree_start_task` | Task not available | STOP. Do not retry. Call `deskfree_state`, pick a different task. |
+| 409 on `deskfree_start_task` | Already claimed | STOP. Do not retry the same taskId. Call `deskfree_state`. |
 | 401 Unauthorized | Token invalid | Check config. Do not retry. |
 
 ### Recovery

package/skills/deskfree/references/tools.md

@@ -3,122 +3,136 @@
 ## Task Status Model
 
 ```
-pending → active → review → done
-                      ↓
-                   pending (if human sends task back via conversation)
+open → done
 ```
 
-- **pending** — Approved, waiting for bot to claim
-- **active** — Bot claimed, runner working
-- **review** — Bot submitted deliverable, waiting for human feedback
+- **open** — Task exists, work can happen
 - **done** — Completed
 
+### Awaiting (whose turn)
+
+| `awaiting` | Meaning |
+|------------|---------|
+| `bot` | Bot should pick this up |
+| `human` | Human needs to respond |
+| `null` | Idle, no one actively needed |
+
+Derived from: `ask` messages set `awaiting: human`, bot claiming sets `awaiting: bot`.
+
+### Message Types
+
+| Type | Surfaces to main | Thread rendering | Sub-agent |
+|------|-----------------|------------------|-----------|
+| `notify` | No | Muted (50% opacity), collapsible | Keeps working |
+| `ask` | Yes | Full prominence | Terminates after sending |
+
+---
+
 ## Orchestrator Tools (5)
 
 ### `deskfree_state`
-Get full workspace snapshot — all tasks, recently done tasks, active initiatives, files, and current ways of working.
+Get full workspace snapshot.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | *(none)* | — | — | — |
 
-**Returns:**
-- `tasks` — active tasks array (includes `fileId` and `fileName` if linked to a file)
-- `recentlyDone` — recently completed tasks (status=done)
-- `waysOfWorking` — global ways of working (string or null)
-- `initiatives` — active initiatives with `{id, title, status, content, contentVersion, taskCount, activeTaskCount}`
-- `files` — all bot files with `{fileId, name, description, contentFormat, version, updatedAt}`
+**Returns:** tasks, recentlyDone, waysOfWorking, initiatives, files.
 
 ---
 
 ### `deskfree_propose`
-Propose a plan for human approval. Nothing is created until the human reviews and approves in a modal. One initiative per call — make multiple calls for multiple initiatives.
+Propose a plan for human approval. Nothing created until human approves.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `initiative` | string \| object | No | Existing initiative ID (e.g. `"INI_123"`) or `{title, content}` to create new |
-| `context` | string | No | Why this plan is being proposed — helps the human understand the reasoning |
-| `tasks` | array | Yes | Array of tasks to propose (1-20) |
-| `tasks[].title` | string | Yes | Task title — short, action-oriented (max 200 chars) |
-| `tasks[].instructions` | string | No | Rich markdown instructions (bold, lists, inline code — no # headers). Include: what to do, steps, what done looks like, constraints. |
-| `tasks[].estimatedTokens` | number | No | Estimated token cost for completing this task |
-| `tasks[].scheduledFor` | string | No | ISO-8601 date for when this task should become available |
-| `tasks[].file` | object | No | `{existingId}` to link existing file, or `{name, description}` to create new on approval |
-
-**Note:** The `substeps` field is deprecated and ignored. Put all steps in the `instructions` field as markdown instead.
-
-**Returns:** Confirmation that proposal was attached to the message.
+| `initiative` | string \| object | No | Existing ID or `{title, content}` for new |
+| `context` | string | No | Why this plan is being proposed |
+| `tasks` | array | Yes | Array of tasks (1-20) |
+| `tasks[].title` | string | Yes | Short, action-oriented (max 200 chars) |
+| `tasks[].instructions` | string | No | Rich markdown (bold, lists, inline code — no # headers) |
+| `tasks[].estimatedTokens` | number | No | Estimated token cost |
+| `tasks[].scheduledFor` | string | No | ISO-8601 date |
+| `tasks[].file` | object | No | `{existingId}` or `{name, description}` |
 
 ---
 
 ### `deskfree_send_message`
-Send a message in the task thread (progress update, question, status report).
+Send a message.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `content` | string | Yes | Message content |
-| `taskId` | string | No | Task UUID (optional — auto-threaded to active task if omitted) |
+| `type` | string | Yes | `notify` (progress, quiet) or `ask` (needs attention, surfaces to main) |
+| `content` | string | Yes | Message content (1-3 sentences) |
+| `taskId` | string | No | Task UUID |
 
 ---
 
-### `deskfree_reopen_task`
-Reopen a completed or review task back to pending.
+### `deskfree_schedule_task`
+Defer or activate a task.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `taskId` | string | Yes | Task UUID to reopen |
+| `taskId` | string | Yes | Task UUID |
+| `scheduledFor` | string | No | ISO-8601 datetime to defer to, or omit/null to activate immediately |
+| `reason` | string | Yes | Why the task is being scheduled/activated |
 
 ---
 
-### `deskfree_update_knowledge`
-Update global ways of working or initiative content. Orchestrator-only — single writer to avoid version conflicts.
+### `deskfree_reopen_task`
+Reopen a done task.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `globalWoW` | string | No | Updated global ways of working content (full replacement) |
-| `initiativeId` | string | No | Initiative to update |
-| `initiativeContent` | string | No | Updated initiative content (required if initiativeId provided) |
-| `reasoning` | string | Yes | Explanation of why knowledge is being updated |
+| `taskId` | string | Yes | Task UUID |
 
 ---
 
 ## Worker Tools (5 — sub-agents only)
 
 ### `deskfree_start_task`
-Claim a `pending` task → moves to `active`. Returns full context.
+Claim an `open` task. Returns full context.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `taskId` | string | Yes | Task UUID to claim |
 
-**Returns:** Full task context — instructions, message history, `parentContext` (title, summary, instructions of the parent task if this was suggested by another task), and `fileContext` (file content + metadata if the task has a linked file).
+**Returns:** Task context — instructions, message history, parentContext, fileContext.
 
-**Errors:** 404 if task not `pending` or doesn't exist. 409 if already claimed.
+**Errors:** 404 if not `open` or doesn't exist. 409 if already claimed.
 
 ---
 
 ### `deskfree_update_file`
-Update a file's content. Build incrementally as you work.
+Update a file's content (full replacement).
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `fileId` | string | Yes | File ID to update |
-| `content` | string | Yes | Full file content — markdown or HTML (replaces previous version) |
+| `fileId` | string | Yes | File ID |
+| `content` | string | Yes | Full content (replaces previous) |
 | `contentFormat` | string | No | `markdown` (default) or `html` |
 
-**Note:** Each call replaces the entire file content. Always send the complete current version.
-
 ---
 
 ### `deskfree_complete_task`
-Finish a task.
+Mark task as done. Optionally update WoW/initiative and propose follow-ups — all in one atomic call.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `taskId` | string | Yes | Task UUID |
-| `outcome` | string | Yes | `review` (submit for human review), `done` (complete), `blocked` (need human input), or `cancelled` |
-| `summary` | string | No | Brief summary of what was accomplished — **required for outcome `done`** (max 2000 chars) |
-| `learnings` | string | No | What was learned during this task — integrated into WoW when task reaches `done` |
+| `learnings` | object | No | Knowledge updates (see below) |
+| `learnings.reasoning` | string | Yes (if learnings) | Why these updates matter |
+| `learnings.globalWoW` | string | No | Updated Ways of Working content (full replacement) |
+
+| `learnings.initiativeContent` | string | No | Updated initiative content (full replacement) |
+| `followUps` | array | No | Follow-up tasks to propose (max 10) |
+| `followUps[].title` | string | Yes | Task title (max 200 chars) |
+| `followUps[].instructions` | string | No | Task instructions |
+
+**Side effects:**
+- WoW update → inserts new version, creates "📝 Updated Ways of Working" message in thread (viewable as diff)
+- Initiative update → stores old + new content, creates "📝 Updated [Initiative]" message (viewable as diff)
+- Follow-ups → creates proposal for human approval
 
 ---
 
@@ -128,4 +142,4 @@ Finish a task.
 ---
 
 ### `deskfree_propose`
-*(Same as orchestrator — see above. Workers can propose follow-up tasks.)*
+*(Same as orchestrator — workers can propose follow-up tasks)*