@questionbase/deskfree 0.3.0-alpha.21 → 0.3.0-alpha.22

package/skills/deskfree/references/tools.md

@@ -1,20 +1,21 @@
 # DeskFree Tools — Full Parameter Reference
 
-## Orchestrator Tools (10)
+## Orchestrator Tools (9)
 
 ### `deskfree_state`
-Get full workspace snapshot — all tasks, recently done tasks, active initiatives, current ways of working, and pending evaluations.
+Get full workspace snapshot — all tasks, recently done tasks, active initiatives, files, current ways of working, and pending evaluations.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | *(none)* | — | — | — |
 
 **Returns:**
-- `tasks` — active tasks array
+- `tasks` — active tasks array (includes `fileId` and `fileName` if linked to a file)
 - `recentlyDone` — recently completed tasks
 - `waysOfWorking` — global ways of working (string or null)
 - `pendingEvaluations` — array of `{taskId, taskNumber, title, initiativeId?}`
 - `initiatives` — active initiatives with `{id, title, status, content, contentVersion, taskCount, activeTaskCount}`
+- `files` — all bot files with `{fileId, name, description, contentFormat, version, updatedAt}`
 
 ---
 
@@ -25,21 +26,36 @@ Claim a `bot` task → moves to `bot` (is_working=true). Returns full context.
 |-----------|------|----------|-------------|
 | `taskId` | string | Yes | Task UUID to claim |
 
-**Returns:** Full task context — instructions, current deliverable, message history, and `parentContext` (title, deliverable, instructions of the parent task if this was suggested by another task). Use this to populate sub-agent spawn prompts.
+**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). Use this to populate sub-agent spawn prompts.
 
 **Errors:** 404 if task not `bot` or doesn't exist. 409 if already claimed.
 
 ---
 
-### `deskfree_update_deliverable`
-Update task deliverable. Build incrementally as you work.
+### `deskfree_update_file`
+Update a file's content. Build incrementally as you work.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `taskId` | string | Yes | Task UUID |
-| `deliverable` | string | Yes | Full markdown deliverable content (replaces previous) |
+| `fileId` | string | Yes | File ID to update |
+| `content` | string | Yes | Full file content — markdown or HTML (replaces previous version) |
+| `contentFormat` | string | No | `markdown` (default) for text/documents, `html` for rich web content rendered in a sandboxed iframe |
 
-**Note:** Each call replaces the entire deliverable. Always send the complete current version, not just new additions.
+**Note:** Each call replaces the entire file content. Always send the complete current version, not just new additions.
+
+---
+
+### `deskfree_create_file`
+Create a new persistent file.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | File name (max 200 chars) |
+| `description` | string | No | Brief description of the file's purpose (max 2000 chars) |
+| `content` | string | No | Initial file content |
+| `contentFormat` | string | No | `markdown` (default) or `html` |
+
+**Returns:** `{ fileId, name }`
 
 ---
 
@@ -50,24 +66,24 @@ Finish a task → moves to `human`.
 |-----------|------|----------|-------------|
 | `taskId` | string | Yes | Task UUID |
 | `outcome` | string | Yes | `done` (work complete) or `blocked` (need human input) |
+| `summary` | string | No | Brief summary of what was accomplished — **required for outcome `done`** (max 2000 chars) |
 
-**Important:** If `blocked`, send a message explaining WHY before calling this.
+**Important:** If `blocked`, send a message explaining WHY before calling this. If `done`, summary is required.
 
 ---
 
 ### `deskfree_send_message`
-Send a message in the task thread (progress update, question, status report).
+Send a message in the task thread (progress update, question, status report). Content is required.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `content` | string | No | Message content. Required unless `suggestions` is provided. |
+| `content` | string | Yes | Message content |
 | `taskId` | string | No | Task UUID (optional — auto-threaded to active task if omitted) |
-| `suggestions` | array | No | List of tasks to suggest for human review (1-10). Prefer `deskfree_suggest_tasks` for richer suggestions with estimatedTokens and dependencies. |
 
 ---
 
 ### `deskfree_suggest_tasks`
-Suggest tasks for human approval. Creates tasks with `suggested` status. Can also propose new initiatives.
+Suggest tasks for human approval. Creates tasks with `suggested` status. Can also propose new initiatives and pre-create linked files.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -75,8 +91,12 @@ Suggest tasks for human approval. Creates tasks with `suggested` status. Can als
 | `suggestions[].title` | string | Yes | Task title — short, action-oriented (max 200 chars) |
 | `suggestions[].instructions` | string | No | Detailed instructions: what to do, why, what done looks like, constraints |
 | `suggestions[].estimatedTokens` | number | No | Estimated token cost for completing this task |
-| `suggestions[].dependsOn` | string[] | No | Task IDs this depends on (blocks claiming until those are done) |
 | `suggestions[].initiativeId` | string | No | Link task to an existing active initiative |
+| `suggestions[].scheduledFor` | string | No | ISO-8601 date for when this task should become available. Use for future-dated or recurring work. |
+| `suggestions[].fileId` | string | No | Link task to an existing file — bot receives file content when claiming |
+| `suggestions[].newFile` | object | No | Pre-create a new file and link it to this task |
+| `suggestions[].newFile.name` | string | Yes (if newFile) | File name (max 200 chars) |
+| `suggestions[].newFile.description` | string | No | File description |
 | `initiativeSuggestions` | array | No | Propose new initiatives (0-5) |
 | `initiativeSuggestions[].title` | string | Yes | Initiative title (max 200 chars) |
 | `initiativeSuggestions[].content` | string | Yes | Initial initiative content (markdown — current state, approach, next priorities) |
@@ -87,27 +107,6 @@ Suggest tasks for human approval. Creates tasks with `suggested` status. Can als
 
 ---
 
-### `deskfree_complete_and_suggest`
-Complete the current task AND suggest follow-up tasks in one atomic call.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `taskId` | string | Yes | Task UUID to complete |
-| `outcome` | string | Yes | `done` or `blocked` |
-| `suggestions` | array | No | Follow-up task suggestions (0-20) |
-| `suggestions[].title` | string | Yes | Task title (max 200 chars) |
-| `suggestions[].instructions` | string | No | Detailed instructions |
-| `suggestions[].estimatedTokens` | number | No | Estimated token cost |
-| `suggestions[].dependsOnTaskIds` | string[] | No | Task IDs this depends on |
-| `suggestions[].initiativeId` | string | No | Link to existing initiative |
-| `initiativeSuggestions` | array | No | Propose new initiatives (same schema as deskfree_suggest_tasks) |
-
-**Returns:** Updated task object + `suggestionIds` array (if suggestions were created) + `initiativeSuggestionIds` (if initiatives were suggested).
-
-**Note:** Deliverable required for outcome `done`. Task moves to `human` for review.
-
----
-
 ### `deskfree_claim_evaluation`
 Claim a pending evaluation. Atomically sets `isWorking=true` where `evaluationPending=true` and `isWorking=false`. Returns null if already claimed.
 
@@ -129,7 +128,7 @@ Submit the result of an evaluation. Supports dual output: global ways of working
 | `globalWoW` | object | Yes | Global ways of working update |
 | `globalWoW.hasChanges` | boolean | Yes | Whether global WoW should be updated |
 | `globalWoW.updatedContent` | string | No | Full updated global WoW markdown (required if hasChanges=true) |
-| `initiative` | object | No | Initiative content update (only if task has initiative_id) |
+| `initiative` | object | Yes | Initiative content update (required — set hasChanges=false if task has no initiative) |
 | `initiative.hasChanges` | boolean | Yes | Whether initiative content should be updated |
 | `initiative.updatedContent` | string | No | Full updated initiative content markdown (required if hasChanges=true) |
 
@@ -137,8 +136,12 @@ Submit the result of an evaluation. Supports dual output: global ways of working
 
 ---
 
-## Worker Tools (4 — sub-agents only)
+## Worker Tools (7 — sub-agents only)
+
+Sub-agents receive: `deskfree_update_file`, `deskfree_create_file`, `deskfree_complete_task`, `deskfree_send_message`, `deskfree_suggest_tasks`, `deskfree_claim_evaluation`, `deskfree_submit_evaluation`
+
+They **cannot** use: `deskfree_state`, `deskfree_start_task`
 
-Sub-agents receive: `deskfree_update_deliverable`, `deskfree_complete_task`, `deskfree_send_message`, `deskfree_submit_evaluation`
+Workers receive workspace context alongside evaluation data (from `deskfree_claim_evaluation`) — use it to understand current workspace state, avoid duplicate suggestions, and link follow-ups to existing initiatives.
 
-They **cannot** use: `deskfree_state`, `deskfree_suggest_tasks`, `deskfree_start_task`, `deskfree_claim_evaluation`
+**Pattern:** After submitting evaluation, reflect and call `deskfree_suggest_tasks` for follow-up opportunities that emerged from your analysis.