@questionbase/deskfree 0.3.0-alpha.35 → 0.3.0-alpha.37

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 (6) hide show
  1. package/dist/index.d.ts +16 -20
  2. package/dist/index.js +286 -132
  3. package/dist/index.js.map +1 -1
  4. package/package.json +1 -1
  5. package/skills/deskfree/SKILL.md +115 -149
  6. package/skills/deskfree/references/tools.md +60 -57
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@questionbase/deskfree",
3
- "version": "0.3.0-alpha.35",
3
+ "version": "0.3.0-alpha.37",
4
4
  "description": "OpenClaw channel plugin for DeskFree — turns DeskFree into a messaging platform for OpenClaw AI agents",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
package/skills/deskfree/SKILL.md CHANGED
@@ -4,12 +4,11 @@ description: >
4
4
  DeskFree task management and human-AI collaboration workflows.
5
5
  Use when: creating tasks, managing work items, updating files,
6
6
  communicating with humans through DeskFree, checking workspace state,
7
- handling task lifecycle (pending → active → review → done),
7
+ handling task lifecycle (start → work → ask → complete),
8
8
  updating ways of working, managing initiatives.
9
9
  Do NOT use for: general project management advice without DeskFree tools,
10
10
  OpenClaw configuration or gateway setup, non-DeskFree platforms (Jira, Asana, etc.),
11
11
  direct file/code operations (use standard tools for those, create DeskFree tasks for tracking).
12
- version: 10.0.0
13
12
  metadata: { 'openclaw': { 'emoji': '🏠' } }
14
13
  ---
15
14
 
@@ -17,215 +16,182 @@ metadata: { 'openclaw': { 'emoji': '🏠' } }
17
16
 
18
17
  ## ⚠️ Critical — Read First
19
18
 
20
- ### Status Model (memorize this)
19
+ ### State Machine
21
20
 
22
21
  ```
23
- pending → active → review → done
22
+ deskfree_propose → [human approves in modal] → bot → [start_task] → bot (is_working)
23
+ ↑ │
24
+ | human approves/declines │
25
+ └──────────────────────────────────────────┘
26
+ │
27
+ [complete_task]
28
+ ↓
29
+ human
30
+ │
31
+ [approve]
32
+ ↓
33
+ done (with optional learnings + follow-ups)
24
34
  ```
25
35
 
26
- - **pending** — Approved, waiting for bot to claim
27
- - **active** — Bot claimed, runner working
28
- - **review** — Bot submitted deliverable, waiting for human feedback
29
- - **done** — Completed
36
+ - Proposals live as metadata on a single message — **NO database rows until human approves**
37
+ - Human reviews everything in a modal: can edit titles, instructions, toggle skills
38
+ - `complete_task` = task is done. Optionally include learnings (WoW/initiative updates) and follow-up proposals.
39
+ - Use `send_message(type: 'ask')` when you need human input — don't complete, just ask.
30
40
 
31
41
  ### The Work Loop
32
42
 
33
43
  ```
34
- 1. Check state → deskfree_state — see tasks, initiatives, files, ways of working
35
- 2. Propose plan → deskfree_propose — propose work for human approval
36
- 3. Claim a task → deskfree_start_task — read instructions + context + fileContext
37
- 4. Do the work → deskfree_update_file — build linked file incrementally
38
- 5. Complete → deskfree_complete_task — with outcome + summary + learnings
44
+ 1. Check state → deskfree_state
45
+ 2. Propose plan → deskfree_propose (qualify the request first — see directive)
46
+ 3. Claim a task → deskfree_start_task
47
+ 4. Load skill → deskfree_read_skill_section (if skills were attached)
48
+ 5. Do the work → deskfree_update_file
49
+ 6. Complete → deskfree_complete_task
50
+ 7. Complete task → deskfree_complete_task (marks done, optionally updates WoW/initiative + proposes follow-ups)
39
51
  ```
40
52
 
41
53
  ### Three Rules
42
54
 
43
- 1. **Always propose first.** Use `deskfree_propose` before starting ANY work. Nothing is created until human approves.
44
- 2. **Always check state first.** Call `deskfree_state` before proposing. Prevents duplicates.
45
- 3. **Always complete tasks.** Never leave a task in `active`. End with `deskfree_complete_task`.
55
+ 1. **Always propose first.** Nothing is created until human approves.
56
+ 2. **Always check state first.** Prevents duplicates, shows active initiatives.
57
+ 3. **Always complete tasks.** Never leave a task in `bot` (is_working=true).
46
58
 
47
59
  ---
48
60
 
49
- ## Tools
61
+ ## How Skills, Initiatives, and Ways of Working Relate
50
62
 
51
- ### Orchestrator (5 tools — main session)
63
+ **Skills** = reusable domain knowledge ("how to do X well"). Attached per-task. The bot gets skill context when claiming a task via `deskfree_start_task`, and can load full details with `deskfree_read_skill_section`.
52
64
 
53
- | Tool | What it does |
54
- |---|---|
55
- | `deskfree_state` | Full workspace snapshot — tasks, done tasks, ways of working, initiatives, files |
56
- | `deskfree_propose` | Propose a plan for human approval — tasks, initiatives, file links |
57
- | `deskfree_send_message` | Message in task thread |
58
- | `deskfree_reopen_task` | Reopen a done/review task back to pending |
59
- | `deskfree_update_knowledge` | Update global ways of working or initiative content |
65
+ **Initiatives** = human aspirations ("where are we going"). Named after outcomes, not activities. Descriptions are 2-3 aspirational sentences — not project plans.
60
66
 
61
- ### Worker (5 tools — sub-agents)
67
+ **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.
62
68
 
63
- | Tool | What it does |
64
- |---|---|
65
- | `deskfree_start_task` | Claim a pending task → active. Returns full context |
66
- | `deskfree_update_file` | Update a linked file's content |
67
- | `deskfree_complete_task` | Complete task with outcome, summary, and learnings |
68
- | `deskfree_send_message` | Message in task thread |
69
- | `deskfree_propose` | Propose follow-up tasks (workers have deepest context) |
69
+ When proposing tasks:
70
+ - Check WoW for established patterns before proposing
71
+ - Check active initiatives — does this work belong to one?
72
+ - Skills are suggested automatically by the matching engine — human toggles them in the modal
70
73
 
71
74
  ---
72
75
 
73
76
  ## Proposing Plans
74
77
 
75
- Proposals are stored as message metadata — **no tasks, files, or initiatives are created until the human approves**.
76
-
77
- ### One Initiative Per Proposal
78
-
79
- Each `deskfree_propose` call handles one initiative (existing or new) or no initiative. Separate calls for separate initiatives.
80
-
81
- ### Task Instructions
82
-
83
- Write instructions as rich markdown — use **bold**, lists, and `inline code`. Do NOT use markdown headers (#); use **bold text** for section labels instead. The human sees these in a rich-text editor and can edit before approving.
78
+ ### Qualify Before Proposing
84
79
 
85
- ```javascript
86
- deskfree_propose({
87
- tasks: [{
88
- title: "Audit auth endpoints",
89
- instructions: "**What to do**\n- Review session management\n- Check CSRF protection\n- Verify rate limiting\n\n**Done when**\nAll endpoints pass security checklist."
90
- }]
91
- })
92
- ```
80
+ Figure out what kind of thing the request is:
81
+ - **One-off task** → propose directly, no initiative needed
82
+ - **New aspiration** → ask 1-2 qualifying questions, then propose an initiative named after the outcome
83
+ - **Task in existing initiative** → add it to the right initiative
93
84
 
94
- ### File Linking
95
-
96
- ```javascript
97
- // Link existing file — bot receives content when claiming
98
- deskfree_propose({
99
- tasks: [{
100
- title: "Update API docs",
101
- file: { existingId: "FILE_abc123" }
102
- }]
103
- })
104
-
105
- // Create new file on approval
106
- deskfree_propose({
107
- tasks: [{
108
- title: "Write deployment runbook",
109
- file: { name: "Deployment Runbook", description: "Step-by-step guide" }
110
- }]
111
- })
112
- ```
85
+ ### Initiative Content
113
86
 
114
- ---
87
+ Initiative descriptions should be 2-3 sentences that reflect the human's ambition. Aspirational, not operational.
115
88
 
116
- ## Completing Tasks
89
+ ```typescript
90
+ // ✅ Good
91
+ initiative: {
92
+ title: "AI Thought Leadership on LinkedIn",
93
+ content: "Position yourself as the go-to voice on AI governance. Build a consistent posting rhythm that turns deep expertise into a public reputation."
94
+ }
117
95
 
118
- ```javascript
119
- deskfree_complete_task({
120
- taskId: "T_abc123",
121
- outcome: "review", // "review" | "done" | "blocked" | "cancelled"
122
- summary: "Implemented auth hardening across all endpoints",
123
- learnings: "Found that rate limiting needs to be per-IP, not per-session"
124
- })
96
+ // ❌ Bad
97
+ initiative: {
98
+ title: "LinkedIn Content",
99
+ content: "# Current State\nNo active presence...\n## Approach\nPhase 1..."
100
+ }
125
101
  ```
126
102
 
127
- - **review** — Submit for human feedback. Human responds in thread, bot reads and decides.
128
- - **done** — Work complete (summary required). Learnings integrated into WoW.
129
- - **blocked** — Need human input. Send a message explaining WHY first.
130
- - **cancelled** — Task no longer needed.
103
+ ### Task Instructions
131
104
 
132
- **Learnings** are only applied to ways of working when a task reaches `done`, not during `review` (human might reject).
105
+ Keep instructions concise. Brief a contractor: what to do, what done looks like. Simple markdown (bold, lists, inline code). **No # headers** — use **bold text** for section labels.
133
106
 
134
107
  ---
135
108
 
136
- ## Conversational Review
137
-
138
- There are no approve/decline buttons. The flow is:
109
+ ## Tools Reference
139
110
 
140
- 1. Bot completes task with outcome `review`
141
- 2. Human responds in the task thread with feedback
142
- 3. Bot reads feedback and either:
143
- - Continues working (task stays active)
144
- - Completes with outcome `done`
145
- - Reopens if major rework needed
111
+ ### Orchestrator Tools (6)
146
112
 
147
- ---
148
-
149
- ## Ways of Working
113
+ | Tool | What it does |
114
+ |---|---|
115
+ | `deskfree_state` | Full workspace snapshot — tasks, done tasks, WoW, initiatives, files |
116
+ | `deskfree_propose` | Propose a plan for human approval — one initiative per call |
117
+ | `deskfree_schedule_task` | Defer or activate a task (pass ISO datetime or null) |
118
+ | `deskfree_reopen_task` | Reopen a completed task back to bot queue |
119
+ | `deskfree_complete_task` | Mark task done, optionally update WoW/initiative + propose follow-ups |
120
+ | `deskfree_send_message` | Send a message to the human (1-3 sentences, no walls of text) |
150
121
 
151
- A single versioned markdown document per bot. Updated via `deskfree_update_knowledge` (orchestrator only — single writer avoids version conflicts).
122
+ ### Worker Tools (7 — sub-agents)
152
123
 
153
- Workers pass `learnings` in `complete_task`. When a task reaches `done`, the orchestrator integrates learnings into WoW via `update_knowledge`.
124
+ | Tool | What it does |
125
+ |---|---|
126
+ | `deskfree_start_task` | Claim task, get full context + skill instructions + file content |
127
+ | `deskfree_read_skill_section` | Load full skill instructions on demand (after claiming) |
128
+ | `deskfree_update_file` | Save work to a linked file (call incrementally) |
129
+ | `deskfree_complete_task` | Mark done (1-2 sentence summary) or blocked |
130
+ | `deskfree_send_message` | Message in task thread (keep it short) |
131
+ | `deskfree_propose` | Propose follow-up tasks if you discover more work |
154
132
 
155
133
  ---
156
134
 
157
- ## Initiatives
158
-
159
- Long-lived areas of focus. Proposed via `deskfree_propose`:
160
-
161
- ```javascript
162
- // Link to existing
163
- deskfree_propose({
164
- initiative: "INI_abc123",
165
- tasks: [...]
166
- })
167
-
168
- // Create new
169
- deskfree_propose({
170
- initiative: { title: "Auth Hardening", content: "# Auth Hardening\n\n..." },
171
- tasks: [...]
172
- })
173
- ```
135
+ ## Decision Tree
174
136
 
175
- ---
137
+ ### Heartbeat / Proactive Check
176
138
 
177
- ## Working with Files
139
+ 1. `deskfree_state` → get workspace snapshot
140
+ 2. `open` tasks with `awaiting: bot` and no active sub-agent? → spawn sub-agents to claim them
141
+ 3. Anything else needing attention? → act on it
178
142
 
179
- Files are persistent documents owned by a bot.
143
+ ### Human Gives You Work
180
144
 
181
- - **Creating:** Via `deskfree_propose` with `file: { name, description }` (created on approval)
182
- - **Updating:** `deskfree_update_file` — always send full content (replaces previous version)
183
- - **Formats:** `markdown` (default) or `html` (for rich web content)
184
- - **Build incrementally** — update early and often. Partial > nothing.
145
+ 1. `deskfree_state` → check existing tasks + initiatives
146
+ 2. Qualify: one-off task, new aspiration, or existing initiative?
147
+ 3. `deskfree_propose` → propose with initiative + context
148
+ 4. [human approves] → spawn sub-agent with taskId
149
+ 5. Sub-agent: `deskfree_start_task` → work → `deskfree_update_file` → `deskfree_complete_task`
185
150
 
186
151
  ---
187
152
 
188
- ## Sub-Agent Pattern
153
+ ## Sub-Agent Flow
189
154
 
190
155
  ```
191
- Orchestrator: deskfree_state → deskfree_propose → (human approves) → spawn sub-agent
156
+ Orchestrator: deskfree_propose → (human approves) → spawn sub-agent with taskId
192
157
  Sub-agent: deskfree_start_task → deskfree_update_file → deskfree_complete_task → terminate
193
158
  ```
194
159
 
195
160
  - One task per sub-agent
196
- - Sub-agent calls `deskfree_start_task` (enables cost attribution via runnerId)
197
- - Orchestrator never claims tasks directly
161
+ - Workers keep messages concise — senior colleague giving a status update, not a report
162
+ - If blocked: send an `ask` message explaining what you need. Sub-agent terminates after ask.
198
163
 
199
164
  ---
200
165
 
201
- ## Decision Tree
166
+ ## Error Handling
202
167
 
203
- ### Heartbeat
204
- 1. `deskfree_state` → get snapshot
205
- 2. `pending` tasks? → spawn sub-agents to claim them
206
- 3. `active` tasks with no active sub-agent? → complete as blocked or resume
168
+ | Error | Cause | Action |
169
+ |---|---|---|
170
+ | `deskfree_state` returns empty | No tasks exist | Create if appropriate. Do NOT retry in a loop. |
171
+ | 404 on `deskfree_start_task` | Task not available | STOP. Do not retry. Call `deskfree_state`, pick a different task. |
172
+ | 409 on `deskfree_start_task` | Already claimed | STOP. Do not retry the same taskId. Call `deskfree_state`. |
173
+ | 401 Unauthorized | Token invalid | Check config. Do not retry. |
207
174
 
208
- ### Human Gives You Work
209
- 1. `deskfree_state` → check existing tasks + initiatives + files
210
- 2. `deskfree_propose` → with context, instructions (markdown), file links, initiative
211
- 3. Human approves → spawn sub-agent → `deskfree_start_task`
212
- 4. Work → `deskfree_update_file` incrementally
213
- 5. `deskfree_complete_task`
175
+ ### Recovery
214
176
 
215
- ---
177
+ 1. Send a message explaining what happened
178
+ 2. Save partial file content
179
+ 3. Complete as `blocked`
180
+ 4. **Never leave a task stranded**
216
181
 
217
- ## Error Handling
182
+ ---
218
183
 
219
- | Error | Action |
220
- |---|---|
221
- | 404 on `start_task` | Task not pending or doesn't exist. Call `deskfree_state`, try another. |
222
- | 409 on `start_task` | Already claimed. Call `deskfree_state`, pick a different task. |
223
- | Empty `deskfree_state` | No tasks exist. Propose if appropriate. **Don't retry in a loop.** |
184
+ ## Best Practices
224
185
 
225
- ### Recovery
186
+ ### ✅ Do This
187
+ - Update files early and often
188
+ - Match the human's energy in messages
189
+ - Provide meaningful 1-2 sentence summaries
190
+ - Check WoW before proposing — follow established patterns
226
191
 
227
- If anything goes wrong mid-task:
228
- 1. `deskfree_send_message` — explain what happened
229
- 2. `deskfree_update_file` — save partial content
230
- 3. `deskfree_complete_task` with outcome `blocked`
231
- 4. **Never leave a task stranded in `active`**
192
+ ### ❌ Don't Do This
193
+ - Leave tasks in `bot` (is_working=true)
194
+ - Retry `deskfree_state` in loops
195
+ - Write walls of text in messages or summaries
196
+ - Use formal structure in initiative descriptions
197
+ - Ignore active initiatives when proposing related work
package/skills/deskfree/references/tools.md CHANGED
@@ -3,122 +3,125 @@
3
3
  ## Task Status Model
4
4
 
5
5
  ```
6
- pending → active → review → done
7
- ↓
8
- pending (if human sends task back via conversation)
6
+ open → done
9
7
  ```
10
8
 
11
- - **pending** — Approved, waiting for bot to claim
12
- - **active** — Bot claimed, runner working
13
- - **review** — Bot submitted deliverable, waiting for human feedback
9
+ - **open** — Task exists, work can happen
14
10
  - **done** — Completed
15
11
 
16
- ## Orchestrator Tools (5)
12
+ ### Awaiting (whose turn)
17
13
 
18
- ### `deskfree_state`
19
- Get full workspace snapshot — all tasks, recently done tasks, active initiatives, files, and current ways of working.
14
+ | `awaiting` | Meaning |
15
+ |------------|---------|
16
+ | `bot` | Bot should pick this up |
17
+ | `human` | Human needs to respond |
18
+ | `null` | Idle, no one actively needed |
20
19
 
21
- | Parameter | Type | Required | Description |
22
- |-----------|------|----------|-------------|
23
- | *(none)* | — | — | — |
20
+ Derived from: `ask` messages set `awaiting: human`, bot claiming sets `awaiting: bot`.
21
+
22
+ ### Message Types
24
23
 
25
- **Returns:**
26
- - `tasks` — active tasks array (includes `fileId` and `fileName` if linked to a file)
27
- - `recentlyDone` — recently completed tasks (status=done)
28
- - `waysOfWorking` — global ways of working (string or null)
29
- - `initiatives` — active initiatives with `{id, title, status, content, contentVersion, taskCount, activeTaskCount}`
30
- - `files` — all bot files with `{fileId, name, description, contentFormat, version, updatedAt}`
24
+ | Type | Surfaces to main | Thread rendering | Sub-agent |
25
+ |------|-----------------|------------------|-----------|
26
+ | `notify` | No | Muted (50% opacity), collapsible | Keeps working |
27
+ | `ask` | Yes | Full prominence | Terminates after sending |
31
28
 
32
29
  ---
33
30
 
34
- ### `deskfree_propose`
35
- 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.
31
+ ## Orchestrator Tools (4)
32
+
33
+ ### `deskfree_state`
34
+ Get full workspace snapshot.
36
35
 
37
36
  | Parameter | Type | Required | Description |
38
37
  |-----------|------|----------|-------------|
39
- | `initiative` | string \| object | No | Existing initiative ID (e.g. `"INI_123"`) or `{title, content}` to create new |
40
- | `context` | string | No | Why this plan is being proposed — helps the human understand the reasoning |
41
- | `tasks` | array | Yes | Array of tasks to propose (1-20) |
42
- | `tasks[].title` | string | Yes | Task title — short, action-oriented (max 200 chars) |
43
- | `tasks[].instructions` | string | No | Rich markdown instructions (bold, lists, inline code — no # headers). Include: what to do, steps, what done looks like, constraints. |
44
- | `tasks[].estimatedTokens` | number | No | Estimated token cost for completing this task |
45
- | `tasks[].scheduledFor` | string | No | ISO-8601 date for when this task should become available |
46
- | `tasks[].file` | object | No | `{existingId}` to link existing file, or `{name, description}` to create new on approval |
47
-
48
- **Note:** The `substeps` field is deprecated and ignored. Put all steps in the `instructions` field as markdown instead.
38
+ | *(none)* | — | — | — |
49
39
 
50
- **Returns:** Confirmation that proposal was attached to the message.
40
+ **Returns:** tasks, recentlyDone, waysOfWorking, initiatives, files.
51
41
 
52
42
  ---
53
43
 
54
- ### `deskfree_send_message`
55
- Send a message in the task thread (progress update, question, status report).
44
+ ### `deskfree_propose`
45
+ Propose a plan for human approval. Nothing created until human approves.
56
46
 
57
47
  | Parameter | Type | Required | Description |
58
48
  |-----------|------|----------|-------------|
59
- | `content` | string | Yes | Message content |
60
- | `taskId` | string | No | Task UUID (optional — auto-threaded to active task if omitted) |
49
+ | `initiative` | string \| object | No | Existing ID or `{title, content}` for new |
50
+ | `context` | string | No | Why this plan is being proposed |
51
+ | `tasks` | array | Yes | Array of tasks (1-20) |
52
+ | `tasks[].title` | string | Yes | Short, action-oriented (max 200 chars) |
53
+ | `tasks[].instructions` | string | No | Rich markdown (bold, lists, inline code — no # headers) |
54
+ | `tasks[].estimatedTokens` | number | No | Estimated token cost |
55
+ | `tasks[].scheduledFor` | string | No | ISO-8601 date |
56
+ | `tasks[].file` | object | No | `{existingId}` or `{name, description}` |
61
57
 
62
58
  ---
63
59
 
64
- ### `deskfree_reopen_task`
65
- Reopen a completed or review task back to pending.
60
+ ### `deskfree_send_message`
61
+ Send a message.
66
62
 
67
63
  | Parameter | Type | Required | Description |
68
64
  |-----------|------|----------|-------------|
69
- | `taskId` | string | Yes | Task UUID to reopen |
65
+ | `type` | string | Yes | `notify` (progress, quiet) or `ask` (needs attention, surfaces to main) |
66
+ | `content` | string | Yes | Message content (1-3 sentences) |
67
+ | `taskId` | string | No | Task UUID |
70
68
 
71
69
  ---
72
70
 
73
- ### `deskfree_update_knowledge`
74
- Update global ways of working or initiative content. Orchestrator-only — single writer to avoid version conflicts.
71
+ ### `deskfree_reopen_task`
72
+ Reopen a done task.
75
73
 
76
74
  | Parameter | Type | Required | Description |
77
75
  |-----------|------|----------|-------------|
78
- | `globalWoW` | string | No | Updated global ways of working content (full replacement) |
79
- | `initiativeId` | string | No | Initiative to update |
80
- | `initiativeContent` | string | No | Updated initiative content (required if initiativeId provided) |
81
- | `reasoning` | string | Yes | Explanation of why knowledge is being updated |
76
+ | `taskId` | string | Yes | Task UUID |
82
77
 
83
78
  ---
84
79
 
85
80
  ## Worker Tools (5 — sub-agents only)
86
81
 
87
82
  ### `deskfree_start_task`
88
- Claim a `pending` task → moves to `active`. Returns full context.
83
+ Claim an `open` task. Returns full context.
89
84
 
90
85
  | Parameter | Type | Required | Description |
91
86
  |-----------|------|----------|-------------|
92
87
  | `taskId` | string | Yes | Task UUID to claim |
93
88
 
94
- **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).
89
+ **Returns:** Task context — instructions, message history, parentContext, fileContext.
95
90
 
96
- **Errors:** 404 if task not `pending` or doesn't exist. 409 if already claimed.
91
+ **Errors:** 404 if not `open` or doesn't exist. 409 if already claimed.
97
92
 
98
93
  ---
99
94
 
100
95
  ### `deskfree_update_file`
101
- Update a file's content. Build incrementally as you work.
96
+ Update a file's content (full replacement).
102
97
 
103
98
  | Parameter | Type | Required | Description |
104
99
  |-----------|------|----------|-------------|
105
- | `fileId` | string | Yes | File ID to update |
106
- | `content` | string | Yes | Full file content — markdown or HTML (replaces previous version) |
100
+ | `fileId` | string | Yes | File ID |
101
+ | `content` | string | Yes | Full content (replaces previous) |
107
102
  | `contentFormat` | string | No | `markdown` (default) or `html` |
108
103
 
109
- **Note:** Each call replaces the entire file content. Always send the complete current version.
110
-
111
104
  ---
112
105
 
113
106
  ### `deskfree_complete_task`
114
- Finish a task.
107
+ Mark task as done. Optionally update WoW/initiative and propose follow-ups — all in one atomic call.
115
108
 
116
109
  | Parameter | Type | Required | Description |
117
110
  |-----------|------|----------|-------------|
118
111
  | `taskId` | string | Yes | Task UUID |
119
- | `outcome` | string | Yes | `review` (submit for human review), `done` (complete), `blocked` (need human input), or `cancelled` |
120
- | `summary` | string | No | Brief summary of what was accomplished — **required for outcome `done`** (max 2000 chars) |
121
- | `learnings` | string | No | What was learned during this task — integrated into WoW when task reaches `done` |
112
+ | `learnings` | object | No | Knowledge updates (see below) |
113
+ | `learnings.reasoning` | string | Yes (if learnings) | Why these updates matter |
114
+ | `learnings.globalWoW` | string | No | Updated Ways of Working content (full replacement) |
115
+
116
+ | `learnings.initiativeContent` | string | No | Updated initiative content (full replacement) |
117
+ | `followUps` | array | No | Follow-up tasks to propose (max 10) |
118
+ | `followUps[].title` | string | Yes | Task title (max 200 chars) |
119
+ | `followUps[].instructions` | string | No | Task instructions |
120
+
121
+ **Side effects:**
122
+ - WoW update → inserts new version, creates "📝 Updated Ways of Working" message in thread (viewable as diff)
123
+ - Initiative update → stores old + new content, creates "📝 Updated [Initiative]" message (viewable as diff)
124
+ - Follow-ups → creates proposal for human approval
122
125
 
123
126
  ---
124
127
 
@@ -128,4 +131,4 @@ Finish a task.
128
131
  ---
129
132
 
130
133
  ### `deskfree_propose`
131
- *(Same as orchestrator — see above. Workers can propose follow-up tasks.)*
134
+ *(Same as orchestrator — workers can propose follow-up tasks)*