@questionbase/deskfree 0.3.0-alpha.35 → 0.3.0-alpha.36
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.
- package/dist/index.js +154 -6
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/skills/deskfree/SKILL.md +115 -149
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@questionbase/deskfree",
|
|
3
|
-
"version": "0.3.0-alpha.
|
|
3
|
+
"version": "0.3.0-alpha.36",
|
|
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 (
|
|
7
|
+
handling task lifecycle (start → work → complete → review),
|
|
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
|
-
###
|
|
19
|
+
### State Machine
|
|
21
20
|
|
|
22
21
|
```
|
|
23
|
-
|
|
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 → update_knowledge
|
|
24
34
|
```
|
|
25
35
|
|
|
26
|
-
-
|
|
27
|
-
-
|
|
28
|
-
-
|
|
29
|
-
-
|
|
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` outcome `done` = work complete (summary required)
|
|
39
|
+
- `complete_task` outcome `blocked` = need human input (send message FIRST explaining why)
|
|
30
40
|
|
|
31
41
|
### The Work Loop
|
|
32
42
|
|
|
33
43
|
```
|
|
34
|
-
1. Check state → deskfree_state
|
|
35
|
-
2. Propose plan → deskfree_propose
|
|
36
|
-
3. Claim a task → deskfree_start_task
|
|
37
|
-
4.
|
|
38
|
-
5.
|
|
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. Update knowledge → deskfree_update_knowledge (orchestrator only, after human approves)
|
|
39
51
|
```
|
|
40
52
|
|
|
41
53
|
### Three Rules
|
|
42
54
|
|
|
43
|
-
1. **Always propose first.**
|
|
44
|
-
2. **Always check state first.**
|
|
45
|
-
3. **Always complete tasks.** Never leave a task in `
|
|
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
|
-
##
|
|
61
|
+
## How Skills, Initiatives, and Ways of Working Relate
|
|
50
62
|
|
|
51
|
-
|
|
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
|
-
|
|
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
|
-
|
|
67
|
+
**Ways of Working (WoW)** = learned preferences ("how WE work together"). Evolves from completed tasks via `deskfree_update_knowledge`. Unique to each bot-human relationship.
|
|
62
68
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
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
|
-
|
|
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
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
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
|
-
###
|
|
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
|
-
|
|
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
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
137
|
-
|
|
138
|
-
There are no approve/decline buttons. The flow is:
|
|
109
|
+
## Tools Reference
|
|
139
110
|
|
|
140
|
-
|
|
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
|
-
|
|
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_update_knowledge` | Update WoW and/or initiative content after task completion |
|
|
120
|
+
| `deskfree_send_message` | Send a message to the human (1-3 sentences, no walls of text) |
|
|
150
121
|
|
|
151
|
-
|
|
122
|
+
### Worker Tools (7 — sub-agents)
|
|
152
123
|
|
|
153
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
139
|
+
1. `deskfree_state` → get workspace snapshot
|
|
140
|
+
2. `bot` tasks with no active sub-agent? → spawn sub-agents to claim them
|
|
141
|
+
3. Anything else needing attention? → act on it
|
|
178
142
|
|
|
179
|
-
|
|
143
|
+
### Human Gives You Work
|
|
180
144
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
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
|
|
153
|
+
## Sub-Agent Flow
|
|
189
154
|
|
|
190
155
|
```
|
|
191
|
-
Orchestrator:
|
|
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
|
-
-
|
|
197
|
-
-
|
|
161
|
+
- Workers keep messages concise — senior colleague giving a status update, not a report
|
|
162
|
+
- If blocked: send message explaining WHY, then complete with outcome "blocked"
|
|
198
163
|
|
|
199
164
|
---
|
|
200
165
|
|
|
201
|
-
##
|
|
166
|
+
## Error Handling
|
|
202
167
|
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
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 | Call `deskfree_state`, try a different task. |
|
|
172
|
+
| 409 on `deskfree_start_task` | Race condition | Call `deskfree_state`, pick a different task. |
|
|
173
|
+
| 401 Unauthorized | Token invalid | Check config. Do not retry. |
|
|
207
174
|
|
|
208
|
-
###
|
|
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
|
-
|
|
182
|
+
---
|
|
218
183
|
|
|
219
|
-
|
|
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
|
-
###
|
|
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
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
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
|