@questionbase/deskfree 0.3.0-alpha.23 → 0.3.0-alpha.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@questionbase/deskfree",
-  "version": "0.3.0-alpha.23",
+  "version": "0.3.0-alpha.24",
   "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

@@ -4,12 +4,12 @@ description: >
   DeskFree task management and human-AI collaboration workflows.
   Use when: creating tasks, managing work items, updating files,
   communicating with humans through DeskFree, checking workspace state,
-  handling task lifecycle (start → work → complete → review),
-  evaluating completed tasks, updating ways of working, managing initiatives.
+  handling task lifecycle (pending → active → review → done),
+  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: 9.0.0
+version: 10.0.0
 metadata: { 'openclaw': { 'emoji': '🏠' } }
 ---
 
@@ -17,73 +17,70 @@ metadata: { 'openclaw': { 'emoji': '🏠' } }
 
 ## ⚠️ Critical — Read First
 
-### State Machine (memorize this)
+### Status Model (memorize this)
 
 ```
-                              🎯 Initiative lifecycle
-deskfree_propose ───────────────────────────────────────────────────────────────┐
-  + initiative →  [human approves initiative in modal] → active                 │
-                  [human rejects]  → nothing created                            │
-                                                                                 │
-deskfree_propose → [human approves in modal] → 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)
+pending → active → review → done
 ```
 
-- Proposals live as metadata on a single message — **NO database rows until human approves**
-- Human reviews everything in one modal: can edit titles, instructions, toggle substeps
-- `complete_task` outcome `done` = work complete (summary required)
-- `complete_task` outcome `blocked` = need human input (send message FIRST explaining why)
-- Both outcomes move to `human` — the human triages from there
+- **pending** — Approved, waiting for bot to claim
+- **active** — Bot claimed, runner working
+- **review** — Bot submitted deliverable, waiting for human feedback
+- **done** — Completed
 
 ### The Work Loop
 
 ```
-1. Check state     → deskfree_state — see tasks, active initiatives, files, pending evaluations
-2. Propose plan    → deskfree_propose — propose work for human approval (one initiative per call)
-3. Claim a task    → deskfree_start_task — read instructions + parent context + fileContext
+1. Check state     → deskfree_state — see tasks, initiatives, files, ways of working
+2. Propose plan    → deskfree_propose — propose work for human approval
+3. Claim a task    → deskfree_start_task — read instructions + context + fileContext
 4. Do the work     → deskfree_update_file — build linked file incrementally
-5. Propose follow-ups → if work reveals more to do, propose them via deskfree_propose
-6. Complete        → deskfree_complete_task — summary required for "done"
-7. Evaluate        → if approved tasks have pending WoW evaluation (update globalWoW + initiative)
+5. Complete        → deskfree_complete_task — with outcome + summary + learnings
 ```
 
-### Three Rules That Break Everything If Ignored
+### Three Rules
 
-1. **Always propose first.** Use `deskfree_propose` before starting ANY work. Nothing is created until human approves. No exceptions.
-2. **Always check state first.** Call `deskfree_state` before proposing. Prevents duplicates, shows active initiatives and files.
-3. **Always complete tasks.** Never leave a task in `bot` (is_working=true). End with `deskfree_complete_task` — outcome `done` or `blocked`.
+1. **Always propose first.** Use `deskfree_propose` before starting ANY work. Nothing is created until human approves.
+2. **Always check state first.** Call `deskfree_state` before proposing. Prevents duplicates.
+3. **Always complete tasks.** Never leave a task in `active`. End with `deskfree_complete_task`.
 
 ---
 
-## Proposing Plans with `deskfree_propose`
+## Tools
 
-**This tool replaces the old `deskfree_suggest_tasks`.** Plans are stored as proposals in message metadata — no tasks, files, or initiatives are created until the human explicitly approves them in a review modal.
+### Orchestrator (5 tools — main session)
 
-### When to Propose vs Just Doing Work
+| Tool | What it does |
+|---|---|
+| `deskfree_state` | Full workspace snapshot — tasks, done tasks, ways of working, initiatives, files |
+| `deskfree_propose` | Propose a plan for human approval — tasks, initiatives, file links |
+| `deskfree_send_message` | Message in task thread |
+| `deskfree_reopen_task` | Reopen a done/review task back to pending |
+| `deskfree_update_knowledge` | Update global ways of working or initiative content |
+
+### Worker (5 tools — sub-agents)
 
-- **Always propose first.** Even quick fixes need a proposal. The human approves what gets created.
-- **Exception:** If you're already working on an approved task, you can create files directly with `deskfree_create_file` during that task.
+| Tool | What it does |
+|---|---|
+| `deskfree_start_task` | Claim a pending task → active. Returns full context |
+| `deskfree_update_file` | Update a linked file's content |
+| `deskfree_complete_task` | Complete task with outcome, summary, and learnings |
+| `deskfree_send_message` | Message in task thread |
+| `deskfree_propose` | Propose follow-up tasks (workers have deepest context) |
+
+---
+
+## Proposing Plans
+
+Proposals are stored as message metadata — **no tasks, files, or initiatives are created until the human approves**.
 
 ### One Initiative Per Proposal
 
-Each `deskfree_propose` call handles **one initiative** (existing or new) or no initiative at all. If you need to propose tasks under multiple initiatives, make separate calls.
+Each `deskfree_propose` call handles one initiative (existing or new) or no initiative. Separate calls for separate initiatives.
 
-### How Substeps Work
+### Substeps
 
-Substeps are **human-reviewable checklist items** within a task. The human can toggle each one on/off before approving:
+Substeps are human-reviewable checklist items. The human can toggle each on/off before approving:
 
 ```javascript
 deskfree_propose({
@@ -93,392 +90,147 @@ deskfree_propose({
     substeps: [
       "Review session management",
       "Check CSRF protection",
-      "Verify rate limiting",
-      "Test token expiration handling"
+      "Verify rate limiting"
     ]
   }]
 })
 ```
 
-In the review modal, the human sees:
-```
-☑ Task: Audit auth endpoints
-  ☑ Review session management
-  ☑ Check CSRF protection
-  ☐ Verify rate limiting          ← human unchecked this
-  ☑ Test token expiration handling
-```
-
-Only checked substeps become part of the approved task.
-
-### File Linking (Existing vs New)
+### File Linking
 
 ```javascript
-// Link an existing file — bot receives its content when claiming the task
+// Link existing file — bot receives content when claiming
 deskfree_propose({
   tasks: [{
     title: "Update API docs",
-    instructions: "...",
     file: { existingId: "FILE_abc123" }
   }]
 })
 
-// Create a new file on approval — for tasks that produce documents
+// Create new file on approval
 deskfree_propose({
   tasks: [{
     title: "Write deployment runbook",
-    instructions: "...",
-    file: { name: "Deployment Runbook", description: "Step-by-step deployment guide" }
+    file: { name: "Deployment Runbook", description: "Step-by-step guide" }
   }]
 })
 ```
 
-New files are created atomically when the human approves — no orphaned files if rejected.
+---
 
-### Examples of Good Proposals
+## Completing Tasks
 
-**Research with file output:**
 ```javascript
-deskfree_propose({
-  initiative: { title: "Competitor Analysis", content: "# Competitor Analysis\n\nSystematic review of key competitors..." },
-  context: "User asked for competitive landscape overview — proposing structured analysis.",
-  tasks: [
-    {
-      title: "Analyze HumanLayer positioning",
-      instructions: "Research HumanLayer's product, pricing, and market position vs DeskFree...",
-      substeps: ["Review public docs and pricing", "Analyze feature comparison", "Draft positioning summary"],
-      file: { name: "HumanLayer Analysis", description: "Competitive analysis report" },
-      estimatedTokens: 20000
-    },
-    {
-      title: "Analyze CrewAI positioning",
-      instructions: "Research CrewAI's product and market position...",
-      substeps: ["Review public docs", "Analyze use cases", "Compare approach"],
-      file: { name: "CrewAI Analysis", description: "Competitive analysis report" },
-      estimatedTokens: 15000
-    }
-  ]
+deskfree_complete_task({
+  taskId: "T_abc123",
+  outcome: "review",     // "review" | "done" | "blocked" | "cancelled"
+  summary: "Implemented auth hardening across all endpoints",
+  learnings: "Found that rate limiting needs to be per-IP, not per-session"
 })
 ```
 
-**Quick fix under existing initiative:**
-```javascript
-deskfree_propose({
-  initiative: "INI_abc123",  // existing initiative ID
-  context: "Found during audit — session fixation vulnerability in /auth/login",
-  tasks: [{
-    title: "Fix session fixation in auth endpoint",
-    instructions: "Regenerate session ID after successful authentication...",
-    substeps: ["Add session regeneration", "Add regression test", "Verify in staging"],
-    estimatedTokens: 10000
-  }]
-})
-```
+- **review** — Submit for human feedback. Human responds in thread, bot reads and decides.
+- **done** — Work complete (summary required). Learnings integrated into WoW.
+- **blocked** — Need human input. Send a message explaining WHY first.
+- **cancelled** — Task no longer needed.
 
-**Scheduled/recurring work:**
-```javascript
-deskfree_propose({
-  context: "Setting up weekly metrics report",
-  tasks: [{
-    title: "Weekly metrics report",
-    instructions: "Generate weekly performance metrics. This recurs weekly on Mondays. When completing, propose the next occurrence.",
-    substeps: ["Pull metrics from dashboard", "Generate summary", "Flag anomalies"],
-    file: { name: "Weekly Metrics", description: "Recurring weekly metrics report" },
-    scheduledFor: "2026-03-02T14:00:00Z"
-  }]
-})
-```
+**Learnings** are only applied to ways of working when a task reaches `done`, not during `review` (human might reject).
 
 ---
 
-## Writing Great Instructions
+## Conversational Review
 
-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 file content when applicable
-- **What "done" looks like** — clear acceptance criteria
-- **Known constraints** — gotchas, dependencies, things to avoid
+There are no approve/decline buttons. The flow is:
 
----
-
-## Working with Files
-
-Files are persistent documents owned by a bot that live across tasks.
-
-```
-deskfree_state() → shows files: [{fileId, name, description, version, updatedAt}, ...]
-
-deskfree_start_task(taskId) → if task.fileId, returns fileContext: {
-  fileId, name, description, content, contentFormat, version
-}
-```
-
-### Creating Files
-
-```javascript
-// Option 1: Pre-create when proposing a task (created on approval)
-deskfree_propose({
-  tasks: [{
-    title: "Write API documentation",
-    instructions: "...",
-    file: { name: "API Reference", description: "Full API reference documentation" }
-  }]
-})
-
-// Option 2: Create a file directly during work
-deskfree_create_file({
-  name: "Deployment Runbook",
-  description: "Step-by-step deployment guide",
-  content: "# Deployment Runbook\n\n...",
-  contentFormat: "markdown"
-})
-```
-
-### Updating Files
-
-```javascript
-// Always send the full current content — each call replaces the previous version
-deskfree_update_file({
-  fileId: "F_abc123",
-  content: "# Full document...",
-  contentFormat: "markdown"  // or "html"
-})
-```
-
-**Build incrementally** — update the file early and often. A half-complete file is infinitely better than none if you're interrupted.
-
-### File Format Choice
-
-| Format | Use when |
-|---|---|
-| `markdown` (default) | Text reports, specs, documentation, analysis, code snippets |
-| `html` | Rich web content: dashboards, styled reports, interactive tables |
+1. Bot completes task with outcome `review`
+2. Human responds in the task thread with feedback
+3. Bot reads feedback and either:
+   - Continues working (task stays active)
+   - Completes with outcome `done`
+   - Reopens if major rework needed
 
 ---
 
-## Initiatives — Long-Lived Areas of Focus
+## Ways of Working
 
-Initiatives answer **"what are we working on and why"** while Ways of Working answers **"how do we work."**
+A single versioned markdown document per bot. Updated via `deskfree_update_knowledge` (orchestrator only — single writer avoids version conflicts).
 
-### When to Propose a New Initiative
+Workers pass `learnings` in `complete_task`. When a task reaches `done`, the orchestrator integrates learnings into WoW via `update_knowledge`.
 
-```
-On every deskfree_propose call, ask yourself:
+---
 
-"Does an active initiative exist that this work belongs to?"
-→ Yes: pass the initiative ID as a string
-→ No, but this is part of a bigger theme: pass { title, content } to create new
-→ No, and it's a one-off task: omit initiative (defaults to General)
-```
+## Initiatives
 
-### Examples
+Long-lived areas of focus. Proposed via `deskfree_propose`:
 
 ```javascript
-// Link to existing initiative
+// Link to existing
 deskfree_propose({
   initiative: "INI_abc123",
-  tasks: [{ title: "Implement CSRF protection", instructions: "..." }]
+  tasks: [...]
 })
 
-// Create new initiative with tasks
+// Create new
 deskfree_propose({
-  initiative: {
-    title: "Auth Hardening",
-    content: "# Auth Hardening\n\n## Current State\nNeed to improve auth security.\n\n## Next Priorities\n1. Audit all endpoints\n2. Address findings"
-  },
-  context: "Starting security improvement initiative based on recent audit findings.",
-  tasks: [
-    { title: "Audit auth endpoints", instructions: "...", estimatedTokens: 20000 },
-    { title: "Add rate limiting", instructions: "...", estimatedTokens: 15000 }
-  ]
+  initiative: { title: "Auth Hardening", content: "# Auth Hardening\n\n..." },
+  tasks: [...]
 })
 ```
 
 ---
 
-## Ways of Working — The Evolving Playbook
-
-Ways of Working is a **single versioned markdown document** per bot that evolves as you complete tasks.
-
-### Evaluation Flow — Dual Output
-
-When a human approves a task, it enters `pendingEvaluations`. Evaluation has **two independent outputs**:
-
-```
-1. deskfree_claim_evaluation(taskId)
-   → returns: task + messages + waysOfWorking + initiative (if task has initiative_id)
-
-2. Review the task summary, messages, and any file output
-
-3. Ask yourself:
-   "Did I learn something about HOW we work that applies everywhere?"
-   → Yes: update globalWoW
-   "Did I learn something about WHERE this initiative stands?"
-   → Yes: update initiative content
-
-4. deskfree_submit_evaluation({ taskId, reasoning, globalWoW, initiative })
-```
-
----
-
-## Validation Gates
-
-### Pre-Flight (before ANY work)
-
-- [ ] Called `deskfree_state` — confirmed it returned data
-- [ ] Read `waysOfWorking` if present — apply established patterns
-- [ ] Read `initiatives` if present — check for active initiatives
-- [ ] Checked `files` list — know what persistent files already exist
-- [ ] Checked for existing tasks that match intent — no duplicates
-- [ ] Proposed via `deskfree_propose` — with initiative, substeps, file links as appropriate
-- [ ] Once approved: called `deskfree_start_task` — confirmed task moved to `bot` (is_working=true)
-- [ ] If task has `fileContext` — read the existing file content before starting work
-
-### Mid-Work
-
-- [ ] File updated immediately after starting task (not waiting until end)
-- [ ] If blocked: sent message explaining WHY before calling `complete_task` with `blocked`
-
-### Pre-Completion
-
-- [ ] File content is non-empty and meaningful (if task produces a file)
-- [ ] Called `deskfree_complete_task` with a clear `summary`
-- [ ] If sub-agent: terminated after completion (one task per sub-agent)
+## Working with Files
 
-### Heartbeat Evaluation Check
+Files are persistent documents owned by a bot.
 
-- [ ] Any `pendingEvaluations` in state? → claim and evaluate each one
+- **Creating:** Via `deskfree_propose` with `file: { name, description }` (created on approval)
+- **Updating:** `deskfree_update_file` — always send full content (replaces previous version)
+- **Formats:** `markdown` (default) or `html` (for rich web content)
+- **Build incrementally** — update early and often. Partial > nothing.
 
 ---
 
-## Task Workflow
-
-### Orchestrator Flow (main session)
-
-```
-1. deskfree_state                  → assess workspace
-2. deskfree_propose                → propose plan (one initiative per call)
-3. deskfree_start_task             → claim approved task
-4. deskfree_update_file            → build linked file incrementally
-5. deskfree_propose                → propose follow-ups if needed
-6. deskfree_complete_task          → complete with outcome done or blocked
-```
-
-### Sub-Agent Flow
+## Sub-Agent Pattern
 
 ```
-Orchestrator: deskfree_propose → (human approves) → deskfree_start_task → spawn sub-agent
-Sub-agent:    deskfree_update_file → deskfree_propose (follow-ups) → deskfree_complete_task → terminate
+Orchestrator: deskfree_state → deskfree_propose → (human approves) → spawn sub-agent
+Sub-agent:    deskfree_start_task → deskfree_update_file → deskfree_complete_task → terminate
 ```
 
-Sub-agents have **7 tools:** `deskfree_update_file`, `deskfree_create_file`, `deskfree_complete_task`, `deskfree_send_message`, `deskfree_propose`, `deskfree_claim_evaluation`, `deskfree_submit_evaluation`.
-
----
-
-## Recurrence — Natural Language + scheduledFor
-
-Recurrence is handled through task instructions + `scheduledFor`. Document the pattern in instructions, set the first occurrence, propagate on completion by proposing the next occurrence.
-
----
-
-## Messaging
-
-**Normal replies:** Just respond — the channel handles routing automatically.
-
-**Use `deskfree_send_message` only for:**
-- Progress updates during task execution
-- Questions needing human input mid-task
-- Status reports for long-running tasks
+- One task per sub-agent
+- Sub-agent calls `deskfree_start_task` (enables cost attribution via runnerId)
+- Orchestrator never claims tasks directly
 
 ---
 
 ## Decision Tree
 
-### Heartbeat / Proactive Check
-
-1. `deskfree_state` → get workspace snapshot
-2. `pendingEvaluations`? → claim and evaluate
-3. `bot` tasks? → `deskfree_start_task` + spawn sub-agents
-4. `bot` (is_working=true) with no active sub-agent? → Complete as blocked or resume
+### Heartbeat
+1. `deskfree_state` → get snapshot
+2. `pending` tasks? → spawn sub-agents to claim them
+3. `active` tasks with no active sub-agent? → complete as blocked or resume
 
 ### Human Gives You Work
-
 1. `deskfree_state` → check existing tasks + initiatives + files
-2. Does this work belong to an active initiative? → pass its ID
-   OR is this starting a new area? → pass { title, content }
-3. `deskfree_propose` → propose with context, substeps, file links
-4. [human approves in modal] → `deskfree_start_task` → claim it
-5. Work → `deskfree_update_file` incrementally
-6. `deskfree_complete_task` → outcome `done` (with summary) or `blocked`
-
----
-
-## Tools Reference
-
-### Orchestrator (9 tools)
-
-| Tool | What it does |
-|---|---|
-| `deskfree_state` | Full workspace snapshot — tasks, done tasks, ways of working, initiatives, files, pending evaluations |
-| `deskfree_propose` | Propose a plan for human approval — one initiative per call, with substeps and file links |
-| `deskfree_start_task` | Claim task → `bot` (is_working=true), returns full context + fileContext |
-| `deskfree_update_file` | Update a linked file's content incrementally |
-| `deskfree_create_file` | Create a new persistent file |
-| `deskfree_complete_task` | Mark done (summary required) or blocked → `human` |
-| `deskfree_send_message` | Message in task thread |
-| `deskfree_claim_evaluation` | Claim a pending evaluation |
-| `deskfree_submit_evaluation` | Submit evaluation with globalWoW + initiative outputs |
-
-### Worker (7 tools — sub-agents only)
-
-`deskfree_update_file`, `deskfree_create_file`, `deskfree_complete_task`, `deskfree_send_message`, `deskfree_propose`, `deskfree_claim_evaluation`, `deskfree_submit_evaluation`
+2. `deskfree_propose` → with context, substeps, file links, initiative
+3. Human approves → spawn sub-agent → `deskfree_start_task`
+4. Work → `deskfree_update_file` incrementally
+5. `deskfree_complete_task`
 
 ---
 
 ## 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. |
-| 409 on `deskfree_start_task` | Race condition | Call `deskfree_state`, pick a different task. |
-| 401 Unauthorized | Bot token invalid | Check channel configuration. Do not retry. |
+| Error | Action |
+|---|---|
+| 404 on `start_task` | Task not pending or doesn't exist. Call `deskfree_state`, try another. |
+| 409 on `start_task` | Already claimed. Call `deskfree_state`, pick a different task. |
+| Empty `deskfree_state` | No tasks exist. Propose if appropriate. **Don't retry in a loop.** |
 
-### Recovery Pattern
+### Recovery
 
 If anything goes wrong mid-task:
-1. Send a message explaining what happened (`deskfree_send_message`)
-2. Save whatever partial file content you have (`deskfree_update_file`)
-3. Complete as `blocked` (`deskfree_complete_task` with outcome `blocked`)
-4. **Never leave a task stranded in `bot` (is_working=true)**
-
----
-
-## Task Title Examples
-
-**Good:** "Research competitor HumanLayer", "Fix auth timeout in Safari", "Write API docs for /users"
-
-**Bad:** "Do some research on a competitor", "There's a bug that needs fixing"
-
----
-
-## Best Practices
-
-### ✅ Do This
-- Update files early and often — shows progress, survives interruptions
-- Use descriptive commit-style titles
-- Send progress messages for long tasks
-- Provide meaningful summary on done
-- Include substeps for multi-step tasks — gives human granular control
-
-### ❌ Don't Do This
-- Leave tasks in `bot` (is_working=true)
-- Retry `deskfree_state` in loops
-- Start multiple sub-agents per task
-- Update file only at the end
-- Skip the context field in proposals — explain your reasoning
-
-## 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.
+1. `deskfree_send_message` — explain what happened
+2. `deskfree_update_file` — save partial content
+3. `deskfree_complete_task` with outcome `blocked`
+4. **Never leave a task stranded in `active`**