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

package/skills/deskfree/SKILL.md

@@ -1,315 +1,604 @@
 ---
 name: deskfree
-description: Workflow knowledge for DeskFree task management and messaging.
-version: 3.0.0
+description: >
+  DeskFree task management and human-AI collaboration workflows.
+  Use when: creating tasks, managing work items, updating deliverables,
+  communicating with humans through DeskFree, checking workspace state,
+  handling task lifecycle (start → work → complete → review),
+  evaluating completed tasks, 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.),
+  direct file/code operations (use standard tools for those, create DeskFree tasks for tracking).
+version: 7.0.0
 metadata: { 'openclaw': { 'emoji': '🏠' } }
 ---
 
 # DeskFree Workflow Guide
 
-> **Overview:** This guide teaches AI agents how to work with DeskFree — a task management platform for human-AI collaboration. Use it to create goals, manage tasks, update deliverables, and communicate with humans through structured workflows.
+## ⚠️ Critical — Read First
 
-## Table of Contents
+### State Machine (memorize this)
 
-- [🚀 Quick Start](#-quick-start)
-- [🎯 Goals](#-goals)
-- [💬 Messaging](#-messaging)
-- [🔁 Auto-Threading](#-auto-threading)
-- [🔄 Task Workflow](#-task-workflow)
-- [🛠️ Tools Reference](#️-tools-reference)
-- [📋 Decision Tree](#-decision-tree)
-- [📝 Deliverable Best Practices](#-deliverable-best-practices)
-- [❌ Error Handling](#-error-handling)
-- [🔧 Troubleshooting](#-troubleshooting)
+```
+                              🎯 Initiative lifecycle
+suggest_tasks ──────────────────────────────────────────────────────────────────┐
+  + initiativeSuggestions →  [human approves initiative] → active               │
+                              [human rejects initiative]  → deleted              │
+                                                                                 │
+suggest_tasks → [human approves] → bot → [start_task] → bot (is_working)       │
+                   ↑                                          │                  │
+                   |               human approves/declines    │                  │
+                   └──────────────────────────────────────────┘                  │
+                                                              │                  │
+                                                         [complete_task]         │
+                                                              ↓                  │
+                                                           human                 │
+                                                              │                  │
+                                                         [approve]               │
+                                                              ↓                  │
+                                                           done ──→ [evaluate] ──┘
+                                                                        ↓
+                                                              globalWoW updated (always)
+                                                              + initiative updated (if task has initiative_id)
+```
 
-## 🚀 Quick Start
+- `complete_task` outcome `done` = work complete for review
+- `complete_task` outcome `blocked` = need human input (send message FIRST explaining why)
+- Both outcomes move to `human` — the human triages from there
+- When human approves (`done`), a pending evaluation is created for ways-of-working update
 
-### Getting Started
+### The Work Loop
 
-When a user starts a conversation, listen for their intent. If they express an ambition or objective ("I want to grow my LinkedIn following"), create a **Goal** — not just a task. Goals drive the entire experience.
+```
+1. Check state     → deskfree_state — see tasks, active initiatives, pending evaluations
+2. Suggest tasks   → deskfree_suggest_tasks — propose work + optional initiative suggestions
+3. Claim a task    → deskfree_start_task — read instructions + parent context
+4. Do the work     → deskfree_update_deliverable — build incrementally
+5. Suggest follow-ups → if work reveals more to do, suggest them (link to initiative)
+6. Complete        → deskfree_complete_and_suggest (or deskfree_complete_task) — deliverable required
+7. Evaluate        → if approved tasks have pending WoW evaluation (update globalWoW + initiative)
+```
 
-## 🎯 Goals
+### Three Rules That Break Everything If Ignored
 
-Goals are the primary way users express what they want to achieve. A goal is a high-level objective broken into actionable tasks.
+1. **Always suggest first.** Use `deskfree_suggest_tasks` before starting ANY work. Tasks go through human approval. No exceptions.
+2. **Always check state first.** Call `deskfree_state` before suggesting tasks. Prevents duplicates, shows active initiatives.
+3. **Always complete tasks.** Never leave a task in `bot` (is_working=true). End with `deskfree_complete_and_suggest` or `deskfree_complete_task` — outcome `done` or `blocked`.
 
-### Goal-Driven Workflow
+### Writing Great Instructions
 
-1. **User states an ambition** → Create a Goal with `deskfree_create_goal`
-2. **Break it down** → Create 3-5 tasks linked to the goal (`deskfree_create_task` with `goalId`)
-3. **Start immediately** → Start the first task and begin working. Don't wait for permission.
-4. **Keep responses SHORT** → "On it. Setting up your goal now." Not a wall of advice.
-5. **Drip tasks** → Never more than 3 pending tasks per goal. When one completes, create the next.
+Write instructions as if briefing a contractor who has never seen the codebase. Include:
+- **What to do** — specific, actionable steps
+- **Why** — referencing parent findings or deliverable when applicable
+- **What "done" looks like** — clear acceptance criteria
+- **Known constraints** — gotchas, dependencies, things to avoid
 
-### When to Create a Goal vs. a Task
+### Deliverable Requirements
 
-| Signal | Action |
-|---|---|
-| "I want to become a LinkedIn influencer" | **Goal** — multi-step objective |
-| "Write a blog post about X" | **Task** — single deliverable |
-| "Help me grow my business" | **Goal** — needs breakdown |
-| "Fix this bug" | **Task** — one action |
+**MUST update deliverable before completing with outcome "done".** Minimum: structured summary of what was found/done, decisions made, and recommendations. An empty or placeholder deliverable will be rejected.
 
-### Goal Health Checks
+### Suggesting Follow-ups
 
-- Use `deskfree_state` to review active goals and pending tasks
-- If a goal has no pending tasks, create the next one
-- If a goal is stale (48h no activity), either create a task or ask the human
-- When all tasks are done and the objective is met, mark goal as completed with `deskfree_update_goal`
+When completing, always consider: does this work reveal follow-up tasks? If yes, suggest them. Your suggestions are strongest at this moment because you have full context.
 
-## 💬 Messaging
+Use `deskfree_complete_and_suggest` to complete and suggest in one atomic call. Estimate token cost per suggestion — consider how many files to read, how much reasoning, how much output.
 
-You are connected to DeskFree via a 1:1 messaging channel. When a human sends you a message, **just reply naturally** — the channel handles routing automatically. You do not need to use any tool to send or receive messages.
+### Building the Chain
 
-- **Inbound:** Human messages appear as regular conversation messages with full context
-- **Outbound:** Your replies are automatically delivered back to the human
-- **Threading:** Messages may be linked to a task ID. When replying in task context, your messages are automatically threaded to that task
-- **Task context:** If you receive a message with task context, your replies will be threaded to that task automatically
+You're not just doing tasks — you're building a chain. The instructions you write become someone else's brief. The deliverable you produce becomes someone else's context. Write both with care.
 
-No special syntax, no user IDs, no targeting required. Just respond to the conversation.
+### Auto-Threading
 
-### Using `deskfree_send_message`
-Use the `deskfree_send_message` tool only for:
-- **Progress updates** during task execution ("Starting phase 2...", "Encountered an issue with X")
-- **Questions** that need human input mid-task ("Should I proceed with approach A or B?")
-- **Status reports** for long-running tasks ("50% complete, ETA 2 hours")
+After `deskfree_start_task`, ALL your outbound messages automatically thread into that task. No need to pass `taskId` to `deskfree_send_message`. After `deskfree_complete_task`, auto-threading stops.
 
-**Don't use it for:** Normal conversation replies (those are handled automatically by the channel).
+The task sidebar is your human's window into your work — every message appears there in real-time.
 
-## 🔁 Auto-Threading
+---
 
-**Your messages are automatically threaded into your active task. No need to specify taskId manually.**
+## Initiatives — Long-Lived Areas of Focus
 
-When you start a task, the plugin tracks it as your "active task." From that point on, **all outbound messages** — whether replies, progress updates, or proactive messages — are automatically threaded into that task's conversation. This means:
+Initiatives answer **"what are we working on and why"** while Ways of Working answers **"how do we work."**
 
-- After `deskfree_start_task`: all your messages thread into that task
-- After `deskfree_complete_task`: auto-threading stops
-- You never need to pass `taskId` to `deskfree_send_message` manually (though you still can to override)
-- The task sidebar shows a complete timeline of your work — every message, every update
+| Concept | What it is |
+|---|---|
+| **Initiative** | A persistent area of focus (e.g. "Auth Hardening", "Performance Sprint") |
+| **Initiative Content** | A versioned markdown doc — current state, approach, next priorities |
+| **Task → Initiative link** | Set `initiativeId` on suggestions to link tasks to an initiative |
 
-**The task sidebar is your human's window into your work. Make it useful.** Every message you send while working on a task appears there, giving your human real-time visibility into progress without them having to ask.
+### When to Propose a New Initiative
 
-## 🔄 Task Workflow
+```
+On every suggest_tasks call, ask yourself:
+
+"Does an active initiative exist that this work belongs to?"
+→ Yes: set initiativeId on the relevant suggestions
+→ No, but this is part of a bigger theme: add an initiativeSuggestion
+→ No, and it's a one-off task: no initiative needed
+```
 
-Tasks follow a strict state machine. Understand this before using any tool.
+### Initiative Suggestion Flow
 
 ```
-create → ready_for_bot → [start_task] → working_on_it → [complete_task] → waiting_for_human
-                ↑                                                              |
-                |              orchestrator triages human reply                 |
-                └──────────────────────────────────────────────────────────────┘
-                                                                               |
-                                                                          [approve] → done
+1. deskfree_state() → check initiatives[] for existing active ones
+
+2. deskfree_suggest_tasks({
+     suggestions: [
+       { title: "Audit auth endpoints", estimatedTokens: 20000 },
+       { title: "Add rate limiting",    estimatedTokens: 15000 }
+     ],
+     initiativeSuggestions: [
+       {
+         title: "Auth Hardening",
+         content: "# Auth Hardening\n\n## Current State\nNeed to improve auth security.\n\n## Approach\nTBD — start with audit.\n\n## Next Priorities\n1. Audit all auth endpoints\n2. Address findings",
+         taskRefs: [0, 1]   // auto-links tasks at index 0 and 1 when approved
+       }
+     ]
+   })
+
+Human sees:
+  🎯 New Initiative: "Auth Hardening"     [Approve] [Reject]
+  📋 Task: "Audit auth endpoints..."      [Approve] [Reject]
+  📋 Task: "Add rate limiting..."         [Approve] [Reject]
 ```
 
-### Statuses
+### Linking Tasks to Existing Initiatives
 
-| Status | Meaning |
-|---|---|
-| `ready_for_bot` | Available for a bot to start |
-| `working_on_it` | A bot is actively working on this task |
-| `waiting_for_human` | Bot completed or is blocked — awaiting human review/input |
-| `done` | Human approved the deliverable |
+```
+deskfree_state() → sees initiatives: [{ id: "init_abc", title: "Auth Hardening", status: "active" }]
+
+deskfree_suggest_tasks({
+  suggestions: [
+    { title: "Implement CSRF protection",
+      instructions: "...",
+      estimatedTokens: 25000,
+      initiativeId: "init_abc"   // link to existing initiative
+    }
+  ]
+  // no initiativeSuggestions needed — initiative already exists
+})
+```
 
-### complete_task outcomes
+---
 
-- **`done`** — Work is complete; deliverable is ready for human review
-- **`blocked`** — Bot needs human input to proceed; send a message explaining the blocker first, then complete as blocked
+## Ways of Working — The Evolving Playbook
 
-Both outcomes move the task to `waiting_for_human`. The human triages from there.
+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.
 
-## 🛠️ Tools Reference
+**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
 
-### Orchestrator tools (8)
+### Evaluation Flow — Dual Output
 
-| Tool | Description |
-|---|---|
-| `deskfree_state` | Full workspace snapshot — goals, tasks, recently done |
-| `deskfree_create_goal` | Create a high-level objective |
-| `deskfree_update_goal` | Update goal status, title, or description |
-| `deskfree_create_task` | Create task (starts as `ready_for_bot`), link to goal with `goalId` |
-| `deskfree_start_task` | Claim a `ready_for_bot` task → `working_on_it`; returns full context (instructions, deliverable, messages) |
-| `deskfree_update_deliverable` | Build the task deliverable incrementally |
-| `deskfree_complete_task` | Mark task done or blocked → `waiting_for_human` |
-| `deskfree_send_message` | Send a message in the task thread |
+When a human approves a task, it enters `pendingEvaluations` in state.get. Evaluation now has **two independent outputs**:
 
-### Worker tools (3 — for sub-agents only)
+```
+1. deskfree_claim_evaluation(taskId)
+   → returns: task + messages + waysOfWorking + initiative (if task has initiative_id)
 
-Sub-agents are ephemeral workers that handle a single task. They receive their context from the spawn prompt (populated from `deskfree_start_task` response) and only have access to:
+2. Read the task deliverable and messages thoroughly
 
-| Tool | Description |
-|---|---|
-| `deskfree_update_deliverable` | Build the task deliverable incrementally |
-| `deskfree_complete_task` | Mark task done or blocked → `waiting_for_human` |
-| `deskfree_send_message` | Send a message in the task thread |
+3. Ask yourself:
+   "Did I learn something about HOW we work that applies everywhere?"
+   → Yes: update globalWoW
 
-Sub-agents **cannot** create goals, create tasks, or read workspace state. They only work on the task they were spawned for.
+   "Did I learn something about WHERE this initiative stands or
+    HOW to approach this specific area?"
+   → Yes: update initiative content
 
-### Self-Tasking
+   Both? → update both
+   Neither? → hasChanges: false for both
 
-**ALWAYS create a task before starting work.** This applies whether a human asked you to do something or you're working proactively. Tasks are cheap — when in doubt, create one.
+4. deskfree_submit_evaluation({
+     taskId,
+     reasoning: "...",
+     globalWoW:  { hasChanges: true,  updatedContent: "..." },
+     initiative: { hasChanges: false }
+   })
+```
 
-**Why:** Tasks give your human visibility into what you're doing, create a paper trail of deliverables, and let you collaborate through comments. Work without a task is invisible work.
+**globalWoW** — patterns that apply to all work everywhere. Examples:
+- A better approach to error handling you discovered
+- A recurring mistake to avoid
+- A tool or service pattern that's universally useful
 
-**Orchestrator flow:**
-1. **Create:** `deskfree_create_task` with a clear title and instructions
-2. **Start:** `deskfree_start_task` with the task ID → moves to `working_on_it`, returns full context
-3. **Work:** Do the work. Start building the deliverable immediately with `deskfree_update_deliverable` — don't wait until the end.
-4. **Complete:** `deskfree_complete_task` with outcome `done` or `blocked`
+**initiative content** — what was learned about this specific area of focus. Examples:
+- Current state of the initiative has changed (task completed a major piece)
+- New findings shifted the approach
+- Next priorities should be reordered
 
-**Sub-agent pattern (recommended for longer tasks):**
-1. Orchestrator creates the task with `deskfree_create_task`
-2. Orchestrator calls `deskfree_start_task` → gets full context (instructions, deliverable, messages)
-3. Orchestrator spawns a sub-agent, passing the task context in the spawn prompt
-4. Sub-agent works, updates deliverable incrementally, then calls `deskfree_complete_task`
-5. Sub-agent terminates — one task per sub-agent, context stays clean
+**When NOT to update either:** One-off tasks with no transferable learnings, standard work that matched existing patterns.
 
-### Task Titles: Examples
+### Example Evaluation
 
-**Good titles (short, scannable, action-oriented):**
-- "Research competitor HumanLayer"
-- "Deploy staging environment hotfix"
-- "Analyze Q3 sales data trends"
-- "Write API documentation for /users endpoint"
+```
+Task "Audit auth endpoints" (linked to "Auth Hardening" initiative) is approved.
+
+claim_evaluation → returns:
+  task (with deliverable showing 3 critical issues found)
+  waysOfWorking: "..."
+  initiative: { id: "init_abc", title: "Auth Hardening", content: "No audit done yet." }
+
+Analysis:
+  - Gateway has built-in rate limiting (just needs config) → applies everywhere → update globalWoW
+  - Audit found 3 critical issues → initiative content needs update → update initiative
+
+submit_evaluation({
+  taskId: "audit-task",
+  reasoning: "Audit found 3 issues. Gateway has rate limiting built in — updated both.",
+  globalWoW: {
+    hasChanges: true,
+    updatedContent: "...## Infrastructure\n- Always check AWS API Gateway config before building custom middleware\n..."
+  },
+  initiative: {
+    hasChanges: true,
+    updatedContent: "# Auth Hardening\n\n## Current State\nAudit complete. Found 3 critical issues:\n1. Session fixation\n2. No rate limiting (gateway supports it — just needs config)\n3. Weak CSRF\n\n## Next Priorities\n1. Configure gateway rate limiting (quick win)\n2. Fix session fixation\n3. Implement CSRF tokens"
+  }
+})
+```
 
-**Bad titles (verbose, unclear scope):**
-- "Do some research on a competitor called HumanLayer and write up findings"
-- "There's a bug in the staging environment that needs to be fixed somehow"
-- "Look at the sales numbers and figure out what's going on"
-- "Document stuff for the API"
+---
+
+## Validation Gates
+
+### Pre-Flight (before ANY work)
+
+- [ ] Called `deskfree_state` — confirmed it returned data (not empty/error)
+- [ ] Read `waysOfWorking` if present — apply established patterns
+- [ ] Read `initiatives` if present — check for active initiatives this work belongs to
+- [ ] Checked for existing tasks that match intent — no duplicates
+- [ ] Suggested a task via `deskfree_suggest_tasks` — with `initiativeId` if linking to existing initiative, or `initiativeSuggestions` if proposing new one
+- [ ] Once approved: called `deskfree_start_task` — confirmed task moved to `bot` (is_working=true)
 
-### When to Use Main Session vs. Sub-Agent
+### Mid-Work
 
-**Stay in main session for:**
-- Quick tasks (< 5 minutes): Simple lookups, config changes, one-liner scripts
-- Interactive work: Tasks requiring back-and-forth with the human
-- Urgent fixes: Immediate response needed, no time for sub-agent setup
+- [ ] Deliverable started immediately after starting task (not waiting until end)
+- [ ] `deskfree_update_deliverable` succeeded (no error response)
+- [ ] If blocked: sent message explaining WHY before calling `complete_task` with `blocked`
 
-**Use sub-agent for:**
-- Research tasks: Multi-step analysis, data gathering, report writing
-- Code development: Writing features, debugging, refactoring
-- Long operations: Tasks taking > 10 minutes or requiring multiple steps
-- Background work: When human might message while you're working
+### Pre-Completion
+
+- [ ] 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 `human`
+- [ ] If sub-agent: terminated after completion (one task per sub-agent)
+
+### Heartbeat Evaluation Check
+
+- [ ] Any `pendingEvaluations` in state? → claim and evaluate each one (submit globalWoW + initiative outputs)
+
+---
+
+## Task Workflow
+
+### Orchestrator Flow (main session)
 
-**Sub-agent handoff pattern:**
 ```
-Orchestrator: deskfree_create_task → deskfree_start_task → spawn sub-agent with task context
-Sub-agent:    (context from spawn prompt) → deskfree_update_deliverable → deskfree_complete_task
+1. deskfree_state                  → assess workspace + read ways of working + check active initiatives
+2. deskfree_suggest_tasks          → suggest tasks (with estimatedTokens, initiativeId, initiativeSuggestions)
+3. deskfree_start_task             → claim approved task (returns full context + parent context)
+4. deskfree_update_deliverable     → build incrementally as you work
+5. deskfree_complete_and_suggest   → complete + suggest follow-ups (or deskfree_complete_task if no follow-ups)
 ```
 
-## 📋 Decision Tree
+### Sub-Agent Flow (recommended for tasks > 5 min)
 
-**Checking for work (heartbeat / proactive loop):**
-1. Call `deskfree_state` to get full workspace snapshot
-2. **Active goals without pending tasks?** Create the next task with `deskfree_create_task`
-3. **`ready_for_bot` tasks?** Check capacity, then `deskfree_start_task` and spawn sub-agents
-4. **Goals with no activity in 48h?** Create a task or send a message nudging the human
-5. **`working_on_it` tasks with no active sub-agent?** Complete as blocked or resume
+```
+Orchestrator: deskfree_suggest_tasks → (human approves) → deskfree_start_task → spawn sub-agent with full task context
+Sub-agent:    deskfree_update_deliverable (incrementally) → deskfree_complete_task → terminate
+```
 
-**When given work by a human (chat message):**
-1. Create a task via `deskfree_create_task`
-2. Start it via `deskfree_start_task`
-3. Work on it, build deliverable incrementally, then `deskfree_complete_task` with outcome `done`
+Sub-agents have **4 tools:** `deskfree_update_deliverable`, `deskfree_complete_task`, `deskfree_send_message` (also supports task suggestions), `deskfree_submit_evaluation`. They cannot suggest tasks, read workspace state, or claim evaluations.
 
-**When blocked:**
-1. Send a message explaining the blocker with `deskfree_send_message`
-2. Then call `deskfree_complete_task` with outcome `blocked`
-3. Terminate — the human will triage
+### When to Use Main vs Sub-Agent
 
-## Human Review Outcomes
+| Main session | Sub-agent |
+|---|---|
+| Quick tasks (< 5 min) | Research, reports, analysis |
+| Interactive/back-and-forth | Code development, debugging |
+| Urgent fixes | Long operations (> 10 min) |
+| | Background work while human may message |
+
+---
+
+## Messaging
+
+**Normal replies:** Just respond — the channel handles routing automatically. No tool needed.
+
+**Use `deskfree_send_message` only for:**
+- Progress updates during task execution
+- Questions needing human input mid-task
+- Status reports for long-running tasks
+
+**Never use it for:** Normal conversation replies (channel handles those).
+
+---
+
+## Decision Tree
+
+### Heartbeat / Proactive Check
+
+1. `deskfree_state` → get workspace snapshot + check `waysOfWorking` + `initiatives` + `pendingEvaluations`
+2. `pendingEvaluations`? → `deskfree_claim_evaluation` → `deskfree_submit_evaluation` (with globalWoW + initiative outputs)
+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 + read ways of working + check active initiatives
+2. Does this work belong to an active initiative? → set `initiativeId` on suggestions
+   OR is this starting a new area of focus? → add `initiativeSuggestions`
+3. `deskfree_suggest_tasks` → suggest with clear title + instructions
+4. [human approves] → `deskfree_start_task` → claim it
+5. Work → `deskfree_update_deliverable` incrementally
+6. `deskfree_complete_task` → outcome `done` or `blocked`
+
+---
+
+## Tools Reference
+
+> **Full parameter details:** See `references/tools.md`
+
+### Orchestrator (10 tools)
+
+| Tool | What it does |
+|---|---|
+| `deskfree_state` | Full workspace snapshot — tasks, recently done, ways of working, active initiatives, pending evaluations |
+| `deskfree_suggest_tasks` | Suggest tasks for human approval (with estimatedTokens, initiativeId, initiativeSuggestions) |
+| `deskfree_start_task` | Claim task → `bot` (is_working=true), returns full context + parent context |
+| `deskfree_update_deliverable` | Build deliverable markdown incrementally |
+| `deskfree_complete_task` | Mark done or blocked → `human` |
+| `deskfree_complete_and_suggest` | Complete current task + suggest follow-ups in one atomic call |
+| `deskfree_send_message` | Message in task thread |
+| `deskfree_claim_evaluation` | Claim a pending evaluation — returns task, messages, globalWoW, and initiative (if applicable) |
+| `deskfree_submit_evaluation` | Submit evaluation with dual output: globalWoW + initiative (each independently updatable) |
+
+### Worker (4 tools — sub-agents only)
 
-- **Approve:** Task moves to `done`. Work is accepted.
-- **Decline / request changes:** Task returns to `ready_for_bot` with feedback. Orchestrator can restart it.
+`deskfree_update_deliverable`, `deskfree_complete_task`, `deskfree_send_message`, `deskfree_submit_evaluation`
 
-## Rules
+---
+
+## Deliverable Best Practices
+
+### 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 |
 
-1. **Always self-task:** Create a DeskFree task before starting work — tasks are cheap, invisible work is expensive
-2. **Build deliverables early:** Start `deskfree_update_deliverable` from the beginning, not at the end
-3. **Use deskfree_state first:** Always read workspace state before creating tasks or starting work
-4. **No manual status changes:** All state transitions happen through the tools above
-5. **Deliverables in markdown:** Build up the deliverable incrementally using `deskfree_update_deliverable`
-6. **Always complete tasks:** End with `deskfree_complete_task` (outcome `done` or `blocked`) — never leave tasks in `working_on_it`
-7. **Blocked means message first:** Before completing as blocked, send a message explaining why
-8. **One task per sub-agent:** Spawn a dedicated sub-agent for each task to keep context clean
-9. **Sub-agents have 3 tools only:** update_deliverable, complete_task, send_message — nothing else
-10. **Auto-threading just works:** Your messages automatically thread into your active task — no manual taskId needed
+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.
 
-## 📝 Deliverable Best Practices
+### Markdown deliverables
 
-Deliverables should be **markdown documents** that stand alone. Structure them like a professional report:
+Structure as **standalone markdown documents:**
 
-### Good Deliverable Structure
 ```markdown
 # Task Title
 
 ## Summary
 Brief overview of what was accomplished.
 
-## Key Findings
-- Main point 1 with supporting detail
-- Main point 2 with supporting detail
+## Key Findings / Results
+- Main points with supporting detail
 
 ## Details
-### Section 1
-Detailed analysis...
-
-### Section 2
-Implementation notes...
+Detailed analysis, implementation notes, etc.
 
 ## Next Steps (if applicable)
-- Recommended follow-up actions
-- Outstanding questions
+- Follow-up actions, outstanding questions
+```
+
+### HTML deliverables
+
+Pass a complete, self-contained HTML document (or fragment — a wrapper `<html>` is injected automatically):
 
-## Resources
-- Links to relevant documentation
-- Code repository URLs
-- External references
+```html
+<h1>Report Title</h1>
+<table>
+  <tr><th>Metric</th><th>Value</th></tr>
+  <tr><td>Users</td><td>1,234</td></tr>
+</table>
 ```
 
-### Incremental Updates
-Start building the deliverable **immediately** when you start a task — don't wait until you're done. Use `deskfree_update_deliverable` to build it up gradually:
+**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.
 
-1. **Start:** Create outline with headers right after starting
-2. **Progress:** Fill in sections as you complete them
-3. **Finish:** Add summary and polish before completing
+---
 
-This gives your human real-time visibility into progress through the task sidebar. A half-complete deliverable is infinitely more useful than no deliverable.
+## Error Handling
+
+| 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 `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 `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
+
+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 `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)
 
-**Example progression:**
 ```
-Update 1: "# Research DeskFree Competitors\n\n## Summary\n[In progress]\n\n## Findings\n### HumanLayer\n- Founded 2023..."
-Update 2: "...### Anthropic Constitutional AI\n- Different approach to human oversight..."
-Update 3: "## Summary\nAnalyzed 3 main competitors. HumanLayer is closest match..."
+Main Session:
+1. deskfree_state()                    → check workspace
+2. deskfree_suggest_tasks([{
+     title: "Research competitor HumanLayer",
+     instructions: "Analyze their product, pricing, and positioning vs DeskFree"
+   }])
+3. [human approves task]
+4. 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")
 ```
 
-## ❌ Error Handling
+### Pattern 2: Quick Fix (Main Session)
 
-| Error | Meaning | Action |
+```
+1. deskfree_state()                    → check current state
+2. deskfree_suggest_tasks([{
+     title: "Fix broken login endpoint", 
+     instructions: "Apply hotfix for 500 error in /auth/login"
+   }])
+3. [human approves task]
+4. 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"  
+- "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 |
 |---|---|---|
-| `deskfree_state` returns no tasks | No work available | Check goals for next task to create; don't loop |
-| 404 on `deskfree_start_task` | Task not in `ready_for_bot` or doesn't exist | Another bot may have started it. Check state and try another task. |
-| 404 on `deskfree_complete_task` | Task not in `working_on_it` status | Check if task was already completed or released |
-| 401 Unauthorized | Bot token invalid | Check channel configuration |
-
-## 🔧 Troubleshooting
-
-### "Task not found" or 404 Errors
-- **Check workspace state** with `deskfree_state` — task may have changed state
-- **Another bot started it** — tasks are first-come-first-served
-
-### Connection Issues
-- **"Channel not configured"** — Run the channel setup flow in OpenClaw
-- **"WebSocket connection failed"** — Check firewall, network connectivity
-- **Messages not arriving** — Verify bot token has correct permissions
-
-### Common Workflow Mistakes
-- **Forgetting to start** — Created task but didn't call `deskfree_start_task` (still `ready_for_bot`)
-- **Working without task** — Doing work without creating/starting a task first
-- **Not completing** — Finished work but didn't call `deskfree_complete_task`
-- **Sub-agent using wrong tools** — Sub-agents only have 3 tools; they cannot read state or create tasks
-- **Completing without messaging when blocked** — Always send a message explaining the blocker before completing as blocked
-
-### Best Practices for Reliability
-1. **Always check state first** — Use `deskfree_state` before creating new tasks
-2. **Handle race conditions** — If start fails, check if another bot got it
-3. **Update deliverable frequently** — Don't wait until the end to document progress
-4. **Include context in messages** — Help humans understand current state when asking questions
+| **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`. Creates pending evaluation for ways-of-working update.
+- **Decline / request changes** → task returns to `bot` with feedback. Restart it.