@questionbase/deskfree 0.1.0

package/skills/deskfree/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: deskfree
+description: Workflow knowledge for DeskFree task management and messaging.
+version: 2.1.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 claim tasks, update deliverables, and communicate with humans through structured workflows.
+
+## Table of Contents
+
+- [🚀 Quick Start](#-quick-start)
+- [💬 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)
+
+## 🚀 Quick Start
+
+### Installation
+
+After installing the DeskFree plugin, run `deskfree_setup` to configure your workspace. This adds the self-tasking directive to your AGENTS.md so you'll always create tasks before starting work.
+
+## 💬 Messaging
+
+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.
+
+- **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
+
+No special syntax, no user IDs, no targeting required. Just respond to the conversation.
+
+### 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")
+
+**Don't use it for:** Normal conversation replies (those are handled automatically by the channel).
+
+## 🔁 Auto-Threading
+
+**Your messages are automatically threaded into your active task. No need to specify taskId manually.**
+
+When you claim 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:
+
+- After `deskfree_claim_task`: all your messages thread into that task
+- After `deskfree_request_review` or `deskfree_release_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
+
+**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.
+
+## 🔄 Task Workflow
+
+Tasks follow a strict state machine. Understand this before using any tool.
+
+```
+ready_for_bot ──[claim]──> working_on_it ──[request_review]──> waiting_for_human ──[approve]──> done
+       ▲              │                              │
+       │        [release]                      [decline]
+       └──────────────┘                              │
+       └─────────────────────────────────────────────┘
+```
+
+### Statuses
+
+| Status | Meaning |
+|---|---|
+| `ready_for_bot` | Available for a bot to claim |
+| `working_on_it` | A bot is actively working on this task |
+| `waiting_for_human` | Bot submitted for human review |
+| `done` | Human approved the deliverable |
+
+## 🛠️ Tools Reference
+
+| Tool | Description |
+|---|---|
+| `deskfree_create_task` | Create a new task (starts as `ready_for_bot`) |
+| `deskfree_list_tasks` | List tasks, optionally filtered by status |
+| `deskfree_get_task` | Fetch full task context by ID (instructions, deliverable, messages) |
+| `deskfree_claim_task` | Claim a specific `ready_for_bot` task → `working_on_it` |
+| `deskfree_release_task` | Release a task back to `ready_for_bot` (failure recovery) |
+| `deskfree_update_deliverable` | Update the task's deliverable markdown incrementally |
+| `deskfree_request_review` | Signal human to review → `waiting_for_human`. Bot should stop after this. |
+| `deskfree_send_message` | Send a message in the task thread (progress updates, questions) |
+| `deskfree_snooze_task` | Snooze a task until a future time (hidden from active views until then) |
+| `deskfree_unsnooze_task` | Unsnooze a task immediately, making it visible again |
+| `deskfree_setup` | One-time setup: returns AGENTS.md directive block |
+
+### Self-Tasking
+
+**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.
+
+**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. The task sidebar is your human's window into your work — make it useful.
+
+**Flow:**
+1. **Create:** `deskfree_create_task` with a clear title and instructions
+2. **Claim:** `deskfree_claim_task` with the task ID to move it to `working_on_it` (auto-threading starts here)
+3. **Work:** Do the work. Start building the deliverable immediately with `deskfree_update_deliverable` — don't wait until the end. Send progress updates naturally; they auto-thread into the task.
+4. **Review:** `deskfree_request_review` when done. The human will approve or decline.
+
+**Sub-agent pattern (recommended for longer tasks):**
+1. Main session creates + claims the task
+2. Spawn a sub-agent with the task ID
+3. Sub-agent calls `deskfree_get_task` to load full context
+4. Sub-agent works, updates deliverable incrementally, then calls `deskfree_request_review`
+5. One task per sub-agent to keep context clean
+
+### Task Titles: Examples
+
+**Good titles (short, scannable, action-oriented):**
+- "Research competitor HumanLayer"
+- "Deploy staging environment hotfix"  
+- "Analyze Q3 sales data trends"
+- "Write API documentation for /users endpoint"
+
+**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"
+
+### When to Use Main Session vs. Sub-Agent
+
+**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
+
+**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
+
+**Sub-agent handoff pattern:**
+```
+Main: deskfree_create_task → deskfree_claim_task → spawn sub-agent with taskId
+Sub:  deskfree_get_task → work → deskfree_update_deliverable → deskfree_request_review  
+```
+
+## 📋 Decision Tree
+
+When checking for work:
+1. Call `deskfree_list_tasks` with `status: "ready_for_bot"` to see available tasks
+2. **Got tasks?** Pick one, `deskfree_claim_task`, then work on it
+3. **Empty list?** No tasks available — stop checking
+4. **Can't complete?** Call `deskfree_release_task` to put it back, or `deskfree_request_review` with a comment explaining the blocker
+
+When given work by a human (chat, Slack, etc.):
+1. Create a task via `deskfree_create_task`
+2. Claim it via `deskfree_claim_task`
+3. Work on it, build deliverable incrementally from the start, then `deskfree_request_review`
+
+## Human Review Outcomes
+
+- **Approve:** Task moves to `done`. Work is accepted.
+- **Decline:** Task moves back to `ready_for_bot` with the human's feedback. Bot can claim and retry with the feedback incorporated.
+
+### Snoozing Tasks
+
+Use `deskfree_snooze_task` to temporarily hide a task from active views until a specific time. This is useful for:
+- Tasks that are blocked until a certain date (e.g., "deploy after Friday's release")
+- Recurring tasks you want to defer until the next scheduled time
+- Reducing clutter in your task list
+
+Use `deskfree_unsnooze_task` to make a snoozed task visible again immediately if priorities change.
+
+## Rules
+
+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. **Status gates:** You can only `request_review` or `release` tasks in `working_on_it` status
+4. **No manual status changes:** All state transitions happen through the tools above
+5. **Deliverables in markdown:** Build up the deliverable incrementally using `update_deliverable`
+6. **Request review, don't just finish:** Always end with `deskfree_request_review` so the human can approve
+7. **Release early:** If you can't complete a task, `deskfree_release_task` to free it — don't spin
+8. **One task per sub-agent:** Spawn a dedicated sub-agent for each task to keep context clean
+9. **No assignment required:** Any bot can claim any `ready_for_bot` task
+10. **Auto-threading just works:** Your messages automatically thread into your active task — no manual taskId needed
+
+## 📝 Deliverable Best Practices
+
+Deliverables should be **markdown documents** that stand alone. Structure them like a professional report:
+
+### 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  
+
+## Details
+### Section 1
+Detailed analysis...
+
+### Section 2  
+Implementation notes...
+
+## Next Steps (if applicable)
+- Recommended follow-up actions
+- Outstanding questions
+
+## Resources
+- Links to relevant documentation
+- Code repository URLs
+- External references
+```
+
+### Incremental Updates
+Start building the deliverable **immediately** when you claim a task — don't wait until you're done. Use `deskfree_update_deliverable` to build it up gradually:
+
+1. **Start:** Create outline with headers right after claiming
+2. **Progress:** Fill in sections as you complete them  
+3. **Finish:** Add summary and polish before review
+
+This gives your human real-time visibility into progress through the task sidebar. A half-complete deliverable is infinitely more useful than no deliverable.
+
+**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..."
+```
+
+## ❌ Error Handling
+
+| Error | Meaning | Action |
+|---|---|---|
+| `deskfree_list_tasks` returns empty | No tasks available | Stop checking — do not retry in a loop |
+| 404 on `deskfree_claim_task` | Task not in `ready_for_bot` or doesn't exist | Another bot may have claimed it. Try a different task. |
+| 404 on `deskfree_request_review` | Task not in `working_on_it` status | Check if task was already reviewed or released |
+| 404 on `deskfree_release_task` | Task not in `working_on_it` status | Task may have been released already |
+| 401 Unauthorized | Bot token invalid | Check channel configuration |
+
+## 🔧 Troubleshooting
+
+### "Task not found" or 404 Errors
+- **Check task status** with `deskfree_get_task` - task may have changed state
+- **List current tasks** with `deskfree_list_tasks` to see what's available  
+- **Another bot claimed 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 claim** - Created task but didn't claim it (still `ready_for_bot`)
+- **Working without task** - Doing work without creating/claiming a task first  
+- **Not requesting review** - Finished work but didn't call `deskfree_request_review`
+- **Duplicate work** - Multiple bots claiming same task type without checking existing tasks
+
+### Best Practices for Reliability
+1. **Always check status first** - Use `deskfree_list_tasks` before creating new tasks
+2. **Handle race conditions** - If claim 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