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

package/skills/deskfree/SKILL.md

@@ -2,14 +2,14 @@
 name: deskfree
 description: >
   DeskFree task management and human-AI collaboration workflows.
-  Use when: creating tasks, managing work items, updating deliverables,
+  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.
   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
+version: 9.0.0
 metadata: { 'openclaw': { 'emoji': '🏠' } }
 ---
 
@@ -21,11 +21,11 @@ metadata: { 'openclaw': { 'emoji': '🏠' } }
 
 ```
                               🎯 Initiative lifecycle
-suggest_tasks ──────────────────────────────────────────────────────────────────┐
-  + initiativeSuggestions →  [human approves initiative] → active               │
-                              [human rejects initiative]  → deleted              │
+deskfree_propose ───────────────────────────────────────────────────────────────┐
+  + initiative →  [human approves initiative in modal] → active                 │
+                  [human rejects]  → nothing created                            │
                                                                                  │
-suggest_tasks → [human approves] → bot → [start_task] → bot (is_working)       │
+deskfree_propose → [human approves in modal] → bot → [start_task] → bot (is_working)
                    ↑                                          │                  │
                    |               human approves/declines    │                  │
                    └──────────────────────────────────────────┘                  │
@@ -42,56 +42,217 @@ suggest_tasks → [human approves] → bot → [start_task] → bot (is_working)
                                                               + initiative updated (if task has initiative_id)
 ```
 
-- `complete_task` outcome `done` = work complete for review
+- 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
-- When human approves (`done`), a pending evaluation is created for ways-of-working update
 
 ### The Work Loop
 
 ```
-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
+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
+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)
 ```
 
 ### Three Rules That Break Everything If Ignored
 
-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`.
+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`.
 
-### Writing Great Instructions
+---
+
+## Proposing Plans with `deskfree_propose`
+
+**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.
+
+### When to Propose vs Just Doing Work
+
+- **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.
+
+### 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.
+
+### How Substeps Work
+
+Substeps are **human-reviewable checklist items** within a task. The human can toggle each one on/off before approving:
+
+```javascript
+deskfree_propose({
+  tasks: [{
+    title: "Audit auth endpoints",
+    instructions: "Review all authentication endpoints for security issues...",
+    substeps: [
+      "Review session management",
+      "Check CSRF protection",
+      "Verify rate limiting",
+      "Test token expiration handling"
+    ]
+  }]
+})
+```
+
+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)
+
+```javascript
+// Link an existing file — bot receives its content when claiming the task
+deskfree_propose({
+  tasks: [{
+    title: "Update API docs",
+    instructions: "...",
+    file: { existingId: "FILE_abc123" }
+  }]
+})
+
+// Create a new file on approval — for tasks that produce documents
+deskfree_propose({
+  tasks: [{
+    title: "Write deployment runbook",
+    instructions: "...",
+    file: { name: "Deployment Runbook", description: "Step-by-step deployment guide" }
+  }]
+})
+```
+
+New files are created atomically when the human approves — no orphaned files if rejected.
+
+### Examples of Good Proposals
+
+**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
+    }
+  ]
+})
+```
+
+**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
+  }]
+})
+```
+
+**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"
+  }]
+})
+```
+
+---
+
+## Writing Great Instructions
 
 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
+- **Why** — referencing parent findings or file content when applicable
 - **What "done" looks like** — clear acceptance criteria
 - **Known constraints** — gotchas, dependencies, things to avoid
 
-### Deliverable Requirements
+---
+
+## Working with Files
+
+Files are persistent documents owned by a bot that live across tasks.
 
-**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.
+```
+deskfree_state() → shows files: [{fileId, name, description, version, updatedAt}, ...]
 
-### Suggesting Follow-ups
+deskfree_start_task(taskId) → if task.fileId, returns fileContext: {
+  fileId, name, description, content, contentFormat, version
+}
+```
 
-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.
+### Creating Files
 
-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.
+```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" }
+  }]
+})
 
-### Building the Chain
+// 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"
+})
+```
 
-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.
+### Updating Files
 
-### Auto-Threading
+```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"
+})
+```
 
-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.
+**Build incrementally** — update the file early and often. A half-complete file is infinitely better than none if you're interrupted.
 
-The task sidebar is your human's window into your work — every message appears there in real-time.
+### File Format Choice
+
+| Format | Use when |
+|---|---|
+| `markdown` (default) | Text reports, specs, documentation, analysis, code snippets |
+| `html` | Rich web content: dashboards, styled reports, interactive tables |
 
 ---
 
@@ -99,62 +260,37 @@ The task sidebar is your human's window into your work — every message appears
 
 Initiatives answer **"what are we working on and why"** while Ways of Working answers **"how do we work."**
 
-| 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 |
-
 ### When to Propose a New Initiative
 
 ```
-On every suggest_tasks call, ask yourself:
+On every deskfree_propose 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
+→ 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)
 ```
 
-### Initiative Suggestion Flow
+### Examples
 
-```
-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]
-```
-
-### Linking Tasks to Existing Initiatives
+```javascript
+// Link to existing initiative
+deskfree_propose({
+  initiative: "INI_abc123",
+  tasks: [{ title: "Implement CSRF protection", instructions: "..." }]
+})
 
-```
-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
-    }
+// Create new initiative with tasks
+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 }
   ]
-  // no initiativeSuggestions needed — initiative already exists
 })
 ```
 
@@ -162,81 +298,25 @@ deskfree_suggest_tasks({
 
 ## Ways of Working — The Evolving Playbook
 
-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 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
+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` in state.get. Evaluation now has **two independent outputs**:
+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. Read the task deliverable and messages thoroughly
+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 or
-    HOW to approach this specific area?"
+   "Did I learn something about WHERE this initiative stands?"
    → Yes: update initiative content
 
-   Both? → update both
-   Neither? → hasChanges: false for both
-
-4. deskfree_submit_evaluation({
-     taskId,
-     reasoning: "...",
-     globalWoW:  { hasChanges: true,  updatedContent: "..." },
-     initiative: { hasChanges: false }
-   })
-```
-
-**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
-
-**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
-
-**When NOT to update either:** One-off tasks with no transferable learnings, standard work that matched existing patterns.
-
-### Example Evaluation
-
-```
-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"
-  }
-})
+4. deskfree_submit_evaluation({ taskId, reasoning, globalWoW, initiative })
 ```
 
 ---
@@ -245,29 +325,29 @@ submit_evaluation({
 
 ### Pre-Flight (before ANY work)
 
-- [ ] Called `deskfree_state` — confirmed it returned data (not empty/error)
+- [ ] Called `deskfree_state` — confirmed it returned data
 - [ ] Read `waysOfWorking` if present — apply established patterns
-- [ ] Read `initiatives` if present — check for active initiatives this work belongs to
+- [ ] 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
-- [ ] Suggested a task via `deskfree_suggest_tasks` — with `initiativeId` if linking to existing initiative, or `initiativeSuggestions` if proposing new one
+- [ ] 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
 
-- [ ] Deliverable started immediately after starting task (not waiting until end)
-- [ ] `deskfree_update_deliverable` succeeded (no error response)
+- [ ] File updated immediately after starting task (not waiting until end)
 - [ ] If blocked: sent message explaining WHY before calling `complete_task` with `blocked`
 
 ### 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`
+- [ ] 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)
 
 ### Heartbeat Evaluation Check
 
-- [ ] Any `pendingEvaluations` in state? → claim and evaluate each one (submit globalWoW + initiative outputs)
+- [ ] Any `pendingEvaluations` in state? → claim and evaluate each one
 
 ---
 
@@ -276,137 +356,82 @@ submit_evaluation({
 ### Orchestrator Flow (main session)
 
 ```
-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)
+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 (recommended for tasks > 5 min)
+### Sub-Agent Flow
 
 ```
-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
+Orchestrator: deskfree_propose → (human approves) → deskfree_start_task → spawn sub-agent
+Sub-agent:    deskfree_update_file → deskfree_propose (follow-ups) → deskfree_complete_task → terminate
 ```
 
-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.
+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`.
 
-### When to Use Main vs Sub-Agent
+---
 
-| 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 |
+## 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. No tool needed.
+**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
 
-**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)
+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
 
 ### 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`
+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
 
-> **Full parameter details:** See `references/tools.md`
-
-### Orchestrator (10 tools)
+### Orchestrator (9 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_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 — returns task, messages, globalWoW, and initiative (if applicable) |
-| `deskfree_submit_evaluation` | Submit evaluation with dual output: globalWoW + initiative (each independently updatable) |
+| `deskfree_claim_evaluation` | Claim a pending evaluation |
+| `deskfree_submit_evaluation` | Submit evaluation with globalWoW + initiative outputs |
 
-### Worker (4 tools — sub-agents only)
+### Worker (7 tools — sub-agents only)
 
-`deskfree_update_deliverable`, `deskfree_complete_task`, `deskfree_send_message`, `deskfree_submit_evaluation`
-
----
-
-## 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 |
-
-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
-
-## Summary
-Brief overview of what was accomplished.
-
-## Key Findings / Results
-- Main points with supporting detail
-
-## Details
-Detailed analysis, implementation notes, etc.
-
-## Next Steps (if applicable)
-- 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.
+`deskfree_update_file`, `deskfree_create_file`, `deskfree_complete_task`, `deskfree_send_message`, `deskfree_propose`, `deskfree_claim_evaluation`, `deskfree_submit_evaluation`
 
 ---
 
@@ -416,187 +441,42 @@ Pass a complete, self-contained HTML document (or fragment — a wrapper `<html>
 |---|---|---|
 | `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. |
+| 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. |
 
 ### 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`)
+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)**
 
-### 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_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")
-```
-
-### Pattern 2: Quick Fix (Main Session)
-
-```
-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"
+**Good:** "Research competitor HumanLayer", "Fix auth timeout in Safari", "Write API docs for /users"
 
-**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"
+**Bad:** "Do some research on a competitor", "There's a bug that needs fixing"
 
 ---
 
-## Best Practices & Anti-Patterns
+## Best Practices
 
 ### ✅ 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 |
+- 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
-
-| 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
+- 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