@questionbase/deskfree 0.3.0-alpha.19 → 0.3.0-alpha.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@questionbase/deskfree",
-  "version": "0.3.0-alpha.19",
+  "version": "0.3.0-alpha.20",
   "description": "OpenClaw channel plugin for DeskFree — turns DeskFree into a messaging platform for OpenClaw AI agents",
   "type": "module",
   "main": "dist/index.js",

package/skills/deskfree/SKILL.md

@@ -5,11 +5,11 @@ description: >
   Use when: creating tasks, managing work items, updating deliverables,
   communicating with humans through DeskFree, checking workspace state,
   handling task lifecycle (start → work → complete → review),
-  classifying tasks against activities, recording learnings.
+  evaluating completed tasks, updating ways of working.
   Do NOT use for: general project management advice without DeskFree tools,
   OpenClaw configuration or gateway setup, non-DeskFree platforms (Jira, Asana, etc.),
   direct file/code operations (use standard tools for those, create DeskFree tasks for tracking).
-version: 5.0.0
+version: 6.0.0
 metadata: { 'openclaw': { 'emoji': '🏠' } }
 ---
 
@@ -20,23 +20,24 @@ metadata: { 'openclaw': { 'emoji': '🏠' } }
 ### State Machine (memorize this)
 
 ```
-create_task → ready_for_bot → [start_task] → working_on_it → [complete_task] → waiting_for_human
+create_task → bot → [start_task] → bot (is_working) → [complete_task] → human
                    ↑                                                                |
                    |                    human approves/declines                     |
                    └────────────────────────────────────────────────────────────────┘
                                                                                     |
-                                                                               [approve] → done
+                                                                               [approve] → done → [evaluate] → ways_of_working updated
 ```
 
 - `complete_task` outcome `done` = work complete for review
 - `complete_task` outcome `blocked` = need human input (send message FIRST explaining why)
-- Both outcomes move to `waiting_for_human` — the human triages from there
+- Both outcomes move to `human` — the human triages from there
+- When human approves (`done`), a pending evaluation is created for ways-of-working update
 
 ### Three Rules That Break Everything If Ignored
 
 1. **Always self-task.** Create a DeskFree task before starting ANY work. Tasks are cheap — invisible work is expensive. No exceptions.
 2. **Always check state first.** Call `deskfree_state` before creating tasks. Prevents duplicates, shows what needs attention.
-3. **Always complete tasks.** Never leave a task in `working_on_it`. End with `deskfree_complete_task` — outcome `done` or `blocked`.
+3. **Always complete tasks.** Never leave a task in `bot` (is_working=true). End with `deskfree_complete_task` — outcome `done` or `blocked`.
 
 ### Auto-Threading
 
@@ -46,40 +47,29 @@ The task sidebar is your human's window into your work — every message appears
 
 ---
 
-## Activities — The Memory System
+## Ways of Working — The Evolving Playbook
 
-Activities are **knowledge containers**, not planning artifacts. They accumulate learnings from completed tasks, building institutional memory over time. Think of them as "how we do X" documents that grow smarter with each task.
+Ways of Working is a **single versioned markdown document** per bot that evolves as you complete tasks. It's your institutional memory — capturing patterns, preferences, and learnings across all work.
 
-**Key mindset shift:** Goals were about planning. Activities are about **memory**. You don't plan work around activities — you classify tasks into activities to retrieve relevant knowledge, then record what you learned back.
+**Key properties:**
+- Injected automatically via `deskfree_state` (the `waysOfWorking` field)
+- Read it before starting work to understand established patterns
+- Updated after task approval via the evaluation flow (never manually during work)
+- Each update creates a new immutable version — full history preserved
 
-### The 3-Phase Activity Loop
+### Evaluation Flow
+
+When a human approves a task, it enters `pendingEvaluations` in state.get:
 
 ```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│  1. CLASSIFY │────>│  2. EXECUTE  │────>│  3. LEARN    │
-│              │     │              │     │              │
-│ Find matching│     │ Use activity │     │ Record what  │
-│ activities   │     │ instructions │     │ was learned  │
-│ for the task │     │ to inform    │     │ back to the  │
-│              │     │ your work    │     │ activity     │
-└─────────────┘     └─────────────┘     └─────────────┘
-       ↑                                       │
-       └───────────────────────────────────────┘
-              Activities get smarter over time
+1. deskfree_claim_evaluation  → claim the eval, get task + messages + current ways of working
+2. Read the task history       → understand what was done and how
+3. deskfree_submit_evaluation → provide reasoning + updated content (or no changes)
 ```
 
-1. **Classify** — Before starting a task, call `deskfree_classify_task` with the task title/instructions. It returns matching activities with their accumulated knowledge.
-2. **Execute** — Read the activity instructions. They contain learnings from previous similar tasks. Use them to inform your approach.
-3. **Learn** — After completing the task, call `deskfree_learn_from_task` to link the task and append what you discovered. Future tasks benefit automatically.
-
-### When to Create Activities
-
-Activities emerge from work — don't pre-create them. Create one when:
-- You finish a task and `deskfree_classify_task` returns no matches (`suggestNew: true`)
-- You notice a recurring type of work with no activity yet
-- The human explicitly asks for one
+**When to update:** New patterns emerged, a better approach was found, recurring mistakes identified, human gave feedback that reveals process improvements.
 
-**Don't create activities for:** one-off tasks, trivial work, or as planning/organizational tools.
+**When NOT to update:** One-off tasks with no transferable learnings, standard work that matched existing patterns.
 
 ---
 
@@ -88,10 +78,10 @@ Activities emerge from work — don't pre-create them. Create one when:
 ### Pre-Flight (before ANY work)
 
 - [ ] Called `deskfree_state` — confirmed it returned data (not empty/error)
+- [ ] Read `waysOfWorking` if present — apply established patterns
 - [ ] Checked for existing tasks that match intent — no duplicates
 - [ ] Created a task with clear, action-oriented title (max 200 chars)
-- [ ] Called `deskfree_start_task` — confirmed task moved to `working_on_it`
-- [ ] Called `deskfree_classify_task` — checked for relevant activity instructions
+- [ ] Called `deskfree_start_task` — confirmed task moved to `bot` (is_working=true)
 
 ### Mid-Work
 
@@ -103,10 +93,13 @@ Activities emerge from work — don't pre-create them. Create one when:
 
 - [ ] Deliverable is non-empty and meaningful (not just headers/placeholders)
 - [ ] Deliverable is well-structured markdown that stands alone
-- [ ] Called `deskfree_complete_task` — confirmed task moved to `waiting_for_human`
-- [ ] Called `deskfree_learn_from_task` if there are useful learnings to record
+- [ ] Called `deskfree_complete_task` — confirmed task moved to `human`
 - [ ] If sub-agent: terminated after completion (one task per sub-agent)
 
+### Heartbeat Evaluation Check
+
+- [ ] Any `pendingEvaluations` in state? → claim and evaluate each one
+
 ---
 
 ## Task Workflow
@@ -114,23 +107,21 @@ Activities emerge from work — don't pre-create them. Create one when:
 ### Orchestrator Flow (main session)
 
 ```
-1. deskfree_state              → assess workspace
+1. deskfree_state              → assess workspace + read ways of working
 2. deskfree_create_task        → create with clear title + instructions
-3. deskfree_classify_task      → find relevant activities for context
-4. deskfree_start_task         → claim it (returns full context)
-5. deskfree_update_deliverable → build incrementally as you work
-6. deskfree_complete_task      → outcome "done" or "blocked"
-7. deskfree_learn_from_task    → record learnings to matching activity
+3. deskfree_start_task         → claim it (returns full context)
+4. deskfree_update_deliverable → build incrementally as you work
+5. deskfree_complete_task      → outcome "done" or "blocked"
 ```
 
 ### Sub-Agent Flow (recommended for tasks > 5 min)
 
 ```
-Orchestrator: deskfree_create_task → deskfree_classify_task → deskfree_start_task → spawn sub-agent with full task context + activity instructions
-Sub-agent:    deskfree_update_deliverable (incrementally) → deskfree_complete_task → deskfree_learn_from_task → terminate
+Orchestrator: deskfree_create_task → deskfree_start_task → spawn sub-agent with full task context
+Sub-agent:    deskfree_update_deliverable (incrementally) → deskfree_complete_task → terminate
 ```
 
-Sub-agents have **5 tools:** `deskfree_update_deliverable`, `deskfree_complete_task`, `deskfree_send_message`, `deskfree_suggest_tasks`, `deskfree_learn_from_task`. They cannot create activities, classify tasks, create tasks, or read workspace state.
+Sub-agents have **4 tools:** `deskfree_update_deliverable`, `deskfree_complete_task`, `deskfree_send_message` (also supports task suggestions), `deskfree_submit_evaluation`. They cannot create tasks, read workspace state, or claim evaluations.
 
 ### When to Use Main vs Sub-Agent
 
@@ -160,19 +151,18 @@ Sub-agents have **5 tools:** `deskfree_update_deliverable`, `deskfree_complete_t
 
 ### Heartbeat / Proactive Check
 
-1. `deskfree_state` → get workspace snapshot
-2. `ready_for_bot` tasks? → `deskfree_classify_task` for context → `deskfree_start_task` + spawn sub-agents
-3. `working_on_it` with no active sub-agent? → Complete as blocked or resume
+1. `deskfree_state` → get workspace snapshot + check `waysOfWorking` + `pendingEvaluations`
+2. `pendingEvaluations`? → `deskfree_claim_evaluation` → `deskfree_submit_evaluation`
+3. `bot` tasks? → `deskfree_start_task` + spawn sub-agents
+4. `bot` (is_working=true) with no active sub-agent? → Complete as blocked or resume
 
 ### Human Gives You Work
 
-1. `deskfree_state` → check existing tasks
+1. `deskfree_state` → check existing tasks + read ways of working
 2. `deskfree_create_task` → clear title + instructions
-3. `deskfree_classify_task` → find relevant activity knowledge
-4. `deskfree_start_task` → claim it
-5. Work → `deskfree_update_deliverable` incrementally
-6. `deskfree_complete_task` → outcome `done` or `blocked`
-7. `deskfree_learn_from_task` → record learnings
+3. `deskfree_start_task` → claim it
+4. Work → `deskfree_update_deliverable` incrementally
+5. `deskfree_complete_task` → outcome `done` or `blocked`
 
 ---
 
@@ -180,31 +170,41 @@ Sub-agents have **5 tools:** `deskfree_update_deliverable`, `deskfree_complete_t
 
 > **Full parameter details:** See `references/tools.md`
 
-### Orchestrator (10 tools)
+### Orchestrator (8 tools)
 
 | Tool | What it does |
 |---|---|
-| `deskfree_state` | Full workspace snapshot — tasks and recently done |
-| `deskfree_create_activity` | Create a knowledge container for a type of work |
-| `deskfree_update_activity` | Update activity name, description, or instructions |
-| `deskfree_classify_task` | Find activities relevant to a task |
-| `deskfree_learn_from_task` | Link task to activity and record learnings |
-| `deskfree_create_task` | Create task (→ `ready_for_bot`) |
-| `deskfree_start_task` | Claim task → `working_on_it`, returns full context |
+| `deskfree_state` | Full workspace snapshot — tasks, recently done, ways of working, pending evaluations |
+| `deskfree_create_task` | Create task (→ `bot`) |
+| `deskfree_start_task` | Claim task → `bot` (is_working=true), returns full context |
 | `deskfree_update_deliverable` | Build deliverable markdown incrementally |
-| `deskfree_complete_task` | Mark done or blocked → `waiting_for_human` |
-| `deskfree_send_message` | Message in task thread |
-| `deskfree_suggest_tasks` | Suggest tasks for human review |
+| `deskfree_complete_task` | Mark done or blocked → `human` |
+| `deskfree_send_message` | Message in task thread (also supports task suggestions) |
+| `deskfree_claim_evaluation` | Claim a pending ways-of-working evaluation |
+| `deskfree_submit_evaluation` | Submit evaluation result with reasoning and optional updated content |
 
-### Worker (5 tools — sub-agents only)
+### Worker (4 tools — sub-agents only)
 
-`deskfree_update_deliverable`, `deskfree_complete_task`, `deskfree_send_message`, `deskfree_suggest_tasks`, `deskfree_learn_from_task`
+`deskfree_update_deliverable`, `deskfree_complete_task`, `deskfree_send_message`, `deskfree_submit_evaluation`
 
 ---
 
 ## Deliverable Best Practices
 
-Structure deliverables as **standalone markdown documents:**
+### Choosing a format
+
+`deskfree_update_deliverable` accepts an optional `format` parameter:
+
+| Format | Use when |
+|---|---|
+| `markdown` (default) | Text reports, analysis, documentation, code — anything prose-based |
+| `html` | Rich web content: dashboards, styled reports, interactive tables, data visualizations |
+
+HTML deliverables are rendered in a **sandboxed iframe** (no access to parent page). Use `format="html"` when layout and styling matter for the human's review. Use `format="markdown"` for everything else.
+
+### Markdown deliverables
+
+Structure as **standalone markdown documents:**
 
 ```markdown
 # Task Title
@@ -222,6 +222,18 @@ Detailed analysis, implementation notes, etc.
 - Follow-up actions, outstanding questions
 ```
 
+### HTML deliverables
+
+Pass a complete, self-contained HTML document (or fragment — a wrapper `<html>` is injected automatically):
+
+```html
+<h1>Report Title</h1>
+<table>
+  <tr><th>Metric</th><th>Value</th></tr>
+  <tr><td>Users</td><td>1,234</td></tr>
+</table>
+```
+
 **Build incrementally** — start with outline immediately after `deskfree_start_task`, fill sections as you go, polish before completing. A half-complete deliverable is infinitely better than none.
 
 ---
@@ -231,13 +243,13 @@ Detailed analysis, implementation notes, etc.
 | Error | Cause | Action |
 |---|---|---|
 | `deskfree_state` returns empty | No tasks exist | Create a task if appropriate. **Do NOT retry in a loop.** |
-| 404 on `deskfree_start_task` | Task not `ready_for_bot` or doesn't exist | Another bot claimed it. Call `deskfree_state`, try a different task. |
-| 404 on `deskfree_complete_task` | Task not `working_on_it` | Already completed or released. Check state. |
+| 404 on `deskfree_start_task` | Task not `bot` or doesn't exist | Another bot claimed it. Call `deskfree_state`, try a different task. |
+| 404 on `deskfree_complete_task` | Task not `bot` (is_working=true) | Already completed or released. Check state. |
 | 409 on `deskfree_start_task` | Race condition — another bot claimed it | Call `deskfree_state`, pick a different task. |
 | 401 Unauthorized | Bot token invalid or expired | Check channel configuration. Do not retry. |
-| `deskfree_update_deliverable` fails | Task not in `working_on_it` or network error | Verify task state with `deskfree_state`. If task was released, re-claim or abort. |
-| `deskfree_classify_task` returns no matches | No activities yet or none relevant | Continue without activity context. Consider creating one after task completion. |
-| Sub-agent spawn fails | Resource limits, config error | Complete task as `blocked` with explanation. Do not leave in `working_on_it`. |
+| `deskfree_update_deliverable` fails | Task not in `bot` (is_working=true) or network error | Verify task state with `deskfree_state`. If task was released, re-claim or abort. |
+| `deskfree_claim_evaluation` returns null | Already claimed by another process | No action needed. Move to next pending evaluation. |
+| Sub-agent spawn fails | Resource limits, config error | Complete task as `blocked` with explanation. Do not leave in `bot` (is_working=true). |
 | WebSocket disconnected | Network issue | Plugin auto-reconnects with backoff. Messages fall back to HTTP polling. No action needed. |
 
 ### Recovery Pattern
@@ -246,24 +258,173 @@ If anything goes wrong mid-task:
 1. Send a message explaining what happened (`deskfree_send_message`)
 2. Save whatever partial deliverable you have (`deskfree_update_deliverable`)
 3. Complete as `blocked` (`deskfree_complete_task` with outcome `blocked`)
-4. **Never leave a task stranded in `working_on_it`**
+4. **Never leave a task stranded in `bot` (is_working=true)**
+
+### Edge Cases & Advanced Scenarios
+
+| Scenario | Guidance |
+|---|---|
+| **Concurrent task access** | If multiple bots try to claim the same task, one will get 409 Conflict. The winner proceeds, losers should call `deskfree_state` and pick different tasks. |
+| **Long-running operations** | For tasks >10 minutes, send periodic progress updates via `deskfree_send_message` so humans know you're still working. Update deliverable incrementally. |
+| **Partial deliverable recovery** | If interrupted mid-work, `deskfree_start_task` returns the current deliverable content. Resume from where you left off, don't start over. |
+| **Network timeouts during updates** | If `deskfree_update_deliverable` times out, retry once. If it fails again, complete as `blocked` with the timeout explanation. |
+| **Empty or corrupt deliverables** | Always validate deliverable content before calling `deskfree_update_deliverable`. Minimum viable content is better than empty/corrupted content. |
+| **Sub-agent coordination** | Only one sub-agent per task. If a sub-agent fails to start, the main session should resume the task directly. Don't spawn multiple sub-agents for the same task. |
+| **Evaluation claim conflicts** | `deskfree_claim_evaluation` returns `null` if another process claimed it first. This is normal - move to the next pending evaluation or complete your heartbeat. |
+| **Ways of working too large** | If ways of working content becomes very large (>50KB), consider archiving old sections. Focus updates on recent patterns and current best practices. |
+
+### Troubleshooting Common Issues
+
+#### "Task not found" (404) Errors
+- **Cause**: Task was claimed by another bot, completed, or deleted
+- **Solution**: Always call `deskfree_state` first to see available tasks
+- **Prevention**: Check task status in state before attempting operations
+
+#### Auto-threading Not Working
+- **Cause**: No active task context, or called `deskfree_complete_task` already
+- **Solution**: Pass explicit `taskId` to `deskfree_send_message`
+- **Debug**: Check that `deskfree_start_task` was called and returned successfully
+
+#### Deliverable Updates Failing
+- **Common causes**:
+  - Task was released by another process → call `deskfree_state` to verify task status
+  - Deliverable content is malformed (invalid markdown, control characters)
+  - Network timeout → retry once, then complete as blocked if persistent
+- **Solution**: Validate markdown content before sending, handle network errors gracefully
+
+#### Sub-agent Spawn Failures
+- **Common causes**: Resource limits, configuration errors, invalid task context
+- **Immediate action**: Main session should resume the task directly
+- **Recovery**: Complete task as `blocked` only if you cannot resume the work yourself
+
+#### Ways of Working Updates Not Applying
+- **Cause**: Another evaluation process updated it first, or `hasChanges=false` was sent
+- **Check**: Ensure `hasChanges=true` and `updatedContent` is provided when you intend to update
+- **Conflict resolution**: If content conflicts occur, the last successful submission wins
+
+#### "State returns empty" Issues
+- **Not an error**: Empty state means no tasks exist - this is normal
+- **Action**: Create a task if you have work to do, otherwise return `HEARTBEAT_OK`
+- **Don't**: Retry `deskfree_state` in a loop - it's not broken
 
 ---
 
+## Common Workflow Patterns
+
+### Pattern 1: Research & Analysis (Sub-agent Recommended)
+
+```
+Main Session:
+1. deskfree_state()                    → check workspace
+2. deskfree_create_task({
+     title: "Research competitor HumanLayer",
+     instructions: "Analyze their product, pricing, and positioning vs DeskFree"
+   })
+3. deskfree_start_task(taskId)         → get task context
+4. spawn_subagent(research_prompt)     → background research
+
+Sub-agent:
+1. deskfree_update_deliverable()       → initial outline
+2. [research work...]
+3. deskfree_update_deliverable()       → interim findings  
+4. [more research...]
+5. deskfree_update_deliverable()       → final report
+6. deskfree_complete_task(taskId, "done")
+```
+
+### Pattern 2: Quick Fix (Main Session)
+
+```
+1. deskfree_state()                    → check current state
+2. deskfree_create_task({
+     title: "Fix broken login endpoint", 
+     instructions: "Apply hotfix for 500 error in /auth/login"
+   })
+3. deskfree_start_task(taskId)         → claim the work
+4. deskfree_update_deliverable()       → "Investigating issue..."
+5. [fix the code...]
+6. deskfree_update_deliverable()       → "Applied fix, testing..."
+7. [verify fix...]
+8. deskfree_update_deliverable()       → "Fix verified and deployed"
+9. deskfree_complete_task(taskId, "done")
+```
+
+### Pattern 3: Blocked Task with Human Input
+
+```
+1-5. [normal task startup...]
+6. [encounter blocker - need API key]
+7. deskfree_send_message("Need the new Stripe API key to complete this integration. Where can I find it?")
+8. deskfree_update_deliverable()       → save partial progress
+9. deskfree_complete_task(taskId, "blocked")  → hand off to human
+```
+
+### Pattern 4: Ways of Working Evaluation
+
+```
+Heartbeat check:
+1. deskfree_state()                    → shows pendingEvaluations: [{taskId: "abc", ...}]
+2. deskfree_claim_evaluation("abc")    → get evaluation context  
+3. [analyze task, messages, current ways of working...]
+4. deskfree_submit_evaluation({
+     taskId: "abc",
+     reasoning: "Found a new pattern for API error handling...",
+     hasChanges: true,
+     updatedContent: "# Ways of Working\n\n## API Integration\n[new section]..."
+   })
+```
+
 ## Task Title Examples
 
 **Good (short, scannable, action-oriented):**
 - "Research competitor HumanLayer"
-- "Deploy staging hotfix"
+- "Deploy staging hotfix"  
 - "Write API docs for /users endpoint"
+- "Debug memory leak in worker process"
+- "Review Q3 performance metrics"
 
 **Bad (verbose, unclear):**
 - "Do some research on a competitor called HumanLayer and write up findings"
 - "There's a bug in staging that needs fixing"
+- "I need to check on some performance stuff for the quarterly review"
 
 ---
 
+## Best Practices & Anti-Patterns
+
+### ✅ Do This
+
+| Practice | Rationale | Example |
+|---|---|---|
+| **Update deliverable early and often** | Shows progress, survives interruptions | Update outline immediately, add sections as you work |
+| **Use descriptive commit-style titles** | Easy to scan, actionable | "Fix authentication timeout in Safari" |
+| **Send progress messages for long tasks** | Humans know you're working | "25% complete - analyzed 3 of 12 competitor features" |
+| **Complete blocked tasks with explanation** | Clear handoff to humans | Message: "Need AWS credentials", then complete as blocked |
+| **Start with template deliverables** | Consistent structure, never empty | Use the markdown template every time |
+| **Handle 404/409 gracefully** | Race conditions are normal | Check state and pick different task, don't retry same task |
+
+### ❌ Don't Do This
+
+| Anti-Pattern | Why It's Bad | Instead |
+|---|---|---|
+| **Leave tasks in `bot` (is_working=true)** | Blocks the workspace indefinitely | Always complete as `done` or `blocked` |
+| **Retry `deskfree_state` in loops** | Wastes resources, indicates logic error | Call once per decision point |
+| **Start multiple sub-agents per task** | Creates confusion, race conditions | One sub-agent per task maximum |
+| **Update deliverable only at the end** | Progress lost if interrupted | Update incrementally throughout work |
+| **Ignore 409 conflicts on task claims** | Causes infinite retry loops | Accept conflict, check state, pick different task |
+| **Create tasks without clear actions** | Unclear what needs doing | Use imperative verbs: "research X", "fix Y", "analyze Z" |
+| **Send messages instead of completing blocked** | Task stays in limbo | Send message explaining blocker, then complete as blocked |
+
+### Common Gotchas
+
+- **Auto-threading stops after `deskfree_complete_task`** → Pass explicit `taskId` for post-completion messages
+- **Empty deliverable content is rejected** → Always provide meaningful content, even if just an outline
+- **Sub-agents can't create tasks** → Only orchestrator (main session) can create and claim tasks  
+- **Ways of working updates require `hasChanges=true`** → Explicitly set flag when submitting changes
+- **Task titles are visible to humans** → Make them professional and descriptive
+- **Evaluation reasoning is important** → Explain your analysis even if no changes are made
+
 ## Human Review Outcomes
 
-- **Approve** → task moves to `done`. Work accepted.
-- **Decline / request changes** → task returns to `ready_for_bot` with feedback. Restart it.
+- **Approve** → task moves to `done`. Creates pending evaluation for ways-of-working update.
+- **Decline / request changes** → task returns to `bot` with feedback. Restart it.

package/skills/deskfree/references/tools.md

@@ -1,74 +1,20 @@
 # DeskFree Tools — Full Parameter Reference
 
-## Orchestrator Tools (10)
+## Orchestrator Tools (8)
 
 ### `deskfree_state`
-Get full workspace snapshot — all tasks and recently done tasks.
+Get full workspace snapshot — all tasks, recently done tasks, current ways of working, and pending evaluations.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | *(none)* | — | — | — |
 
-**Returns:** Active tasks array, recently completed tasks.
-
----
-
-### `deskfree_create_activity`
-Create an activity — a knowledge container for a type of work. Activities accumulate learnings from tasks.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `name` | string | Yes | Activity name (max 200 chars) |
-| `description` | string | No | What this activity covers (max 50,000 chars) |
-| `instructions` | string | No | Initial instructions/knowledge (max 50,000 chars) |
-
-**Returns:** `{ activity }` — created activity object with ID.
-
----
-
-### `deskfree_update_activity`
-Update an activity's name, description, or instructions.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `activityId` | string | Yes | Activity ID to update (max 16 chars) |
-| `name` | string | No | New name (max 200 chars) |
-| `description` | string | No | Updated description (max 50,000 chars) |
-| `instructions` | string | No | Updated instructions (max 50,000 chars) |
-
-**Returns:** `{ activity }` — updated activity object.
-
----
-
-### `deskfree_classify_task`
-Find activities relevant to a task. Returns matching activities whose instructions should inform the task.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `taskTitle` | string | Yes | Task title to classify (max 200 chars) |
-| `taskInstructions` | string | No | Task instructions for better matching (max 50,000 chars) |
-
-**Returns:** `{ matches, suggestNew }` — array of matching activities (with score), and boolean suggesting whether to create a new activity.
-
----
-
-### `deskfree_learn_from_task`
-After completing a task, link it to an activity and record what was learned. Appends new instructions to the activity.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `taskId` | string | Yes | Task UUID |
-| `activityId` | string | Yes | Activity ID to learn into (max 16 chars) |
-| `additionalInstructions` | string | No | New learnings to append (max 50,000 chars) |
-
-**Returns:** `{ activity }` — updated activity with incremented taskCount and appended instructions.
-
-**Note:** Safe to call multiple times for the same task/activity pair (upserts the link).
+**Returns:** Active tasks array, recently completed tasks, `waysOfWorking` (string or null), `pendingEvaluations` (array of `{taskId, taskNumber, title}`).
 
 ---
 
 ### `deskfree_create_task`
-Create a new task (starts as `ready_for_bot`).
+Create a new task (starts as `bot`).
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -78,7 +24,7 @@ Create a new task (starts as `ready_for_bot`).
 ---
 
 ### `deskfree_start_task`
-Claim a `ready_for_bot` task → moves to `working_on_it`. Returns full context.
+Claim a `bot` task → moves to `bot` (is_working=true). Returns full context.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -86,7 +32,7 @@ Claim a `ready_for_bot` task → moves to `working_on_it`. Returns full context.
 
 **Returns:** Full task context — instructions, current deliverable, message history. Use this to populate sub-agent spawn prompts.
 
-**Errors:** 404 if task not `ready_for_bot` or doesn't exist. 409 if already claimed.
+**Errors:** 404 if task not `bot` or doesn't exist. 409 if already claimed.
 
 ---
 
@@ -103,7 +49,7 @@ Update task deliverable. Build incrementally as you work.
 ---
 
 ### `deskfree_complete_task`
-Finish a task → moves to `waiting_for_human`.
+Finish a task → moves to `human`.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -115,27 +61,43 @@ Finish a task → moves to `waiting_for_human`.
 ---
 
 ### `deskfree_send_message`
-Send a message in the task thread.
+Send a message in the task thread. Can also suggest follow-up tasks for human review.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `content` | string | Yes | Message content |
+| `content` | string | No | Message content. Required unless `suggestions` is provided. |
 | `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), each with `title` (required) and `instructions` (optional). Provide this instead of `content`. |
 
 ---
 
-### `deskfree_suggest_tasks`
-Suggest new tasks for the human to review and approve.
+### `deskfree_claim_evaluation`
+Claim a pending ways-of-working evaluation. Atomically sets `isWorking=true` where `evaluationPending=true` and `isWorking=false`. Returns null if already claimed.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `tasks` | array | Yes | List of tasks to suggest (1-10), each with `title` (required) and `instructions` (optional) |
-| `taskId` | string | No | Current task UUID — links suggestions to the task you are working on |
+| `taskId` | string | Yes | Task UUID from `pendingEvaluations` list |
+
+**Returns:** `{ task, waysOfWorking, currentVersion, messages }` — full evaluation context, or `null` if already claimed.
+
+---
+
+### `deskfree_submit_evaluation`
+Submit the result of a ways-of-working evaluation. Always call this after `deskfree_claim_evaluation`.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `taskId` | string | Yes | Task UUID being evaluated |
+| `reasoning` | string | Yes | Explanation of your analysis — what you learned and why you did or did not update ways of working |
+| `hasChanges` | boolean | Yes | Whether the ways of working should be updated |
+| `updatedContent` | string | No | Full updated ways-of-working markdown (required if `hasChanges=true`) |
+
+**Returns:** `{ success, version }` — version number of the new ways-of-working entry (if hasChanges=true).
 
 ---
 
-## Worker Tools (5 — sub-agents only)
+## Worker Tools (4 — sub-agents only)
 
-Sub-agents receive: `deskfree_update_deliverable`, `deskfree_complete_task`, `deskfree_send_message`, `deskfree_suggest_tasks`, `deskfree_learn_from_task`
+Sub-agents receive: `deskfree_update_deliverable`, `deskfree_complete_task`, `deskfree_send_message`, `deskfree_submit_evaluation`
 
-They **cannot** use: `deskfree_state`, `deskfree_create_activity`, `deskfree_update_activity`, `deskfree_classify_task`, `deskfree_create_task`, `deskfree_start_task`
+They **cannot** use: `deskfree_state`, `deskfree_create_task`, `deskfree_start_task`, `deskfree_claim_evaluation`