@kanvas/openclaw-plugin 0.1.17 → 0.1.19

package/README.md

@@ -1,6 +1,6 @@
 # Kanvas OpenClaw Plugin
 
-OpenClaw plugin that connects AI agents to [Kanvas](https://kanvas.dev) — your company's nervous system. Kanvas is the operational engine that connects all your data, tools, and workflows. For AI agents, it's what lets them actually run your business — not just talk about it.
+OpenClaw plugin that connects AI agents to [Kanvas](https://kanvas.dev) your company's nervous system. Kanvas is the operational engine that connects all your data, tools, and workflows. For AI agents, it's what lets them actually run your business — not just talk about it.
 
 This plugin gives agents direct access to CRM, inventory, orders, and messaging — 53 tools with auto-login, built-in system prompt context, and domain-specific skills.
 

package/dist/domains/nervousSystem/index.js

@@ -0,0 +1,203 @@
+const PLAN_DETAIL_FIELDS = `
+  id
+  uuid
+  title
+  description
+  plan_type
+  status
+  priority
+  deadline_at
+  completion_pct
+  requires_human_approval
+  approved_at
+  review_outcome
+  started_at
+  completed_at
+  error_message
+  input
+  output
+  confidence_score
+  entity_namespace
+  entity_id
+  created_at
+  updated_at
+  agent { id name }
+  user { id firstname lastname }
+  approver { id firstname lastname }
+  parent { id title status }
+  tasks { id sequence title description status blocked_reason result started_at completed_at }
+  files { data { id uuid name url } }
+  tags { data { id name } }
+`;
+const PLAN_LIST_FIELDS = `
+  id
+  uuid
+  title
+  description
+  plan_type
+  status
+  priority
+  deadline_at
+  completion_pct
+  requires_human_approval
+  entity_namespace
+  entity_id
+  created_at
+  agent { id name }
+  tasks { id sequence title status blocked_reason }
+`;
+const TASK_FIELDS = `
+  id
+  uuid
+  sequence
+  title
+  description
+  status
+  blocked_reason
+  result
+  started_at
+  completed_at
+  created_at
+  updated_at
+`;
+export class NervousSystemService {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    // ── Read ───────────────────────────────────────────────────
+    async listMyPlans(opts) {
+        const { agent_id, statuses, first = 50 } = opts;
+        const where = statuses && statuses.length
+            ? {
+                AND: [
+                    { column: "AGENT_ID", operator: "EQ", value: agent_id },
+                    { column: "STATUS", operator: "IN", value: statuses },
+                ],
+            }
+            : { column: "AGENT_ID", operator: "EQ", value: agent_id };
+        const query = `
+      query MyPlans($first: Int!, $where: QueryNervousSystemPlansWhereWhereConditions) {
+        nervousSystemPlans(
+          first: $first
+          where: $where
+          orderBy: [{ column: PRIORITY, order: DESC }, { column: DEADLINE_AT, order: ASC }]
+        ) {
+          data { ${PLAN_LIST_FIELDS} }
+          paginatorInfo { currentPage lastPage total }
+        }
+      }
+    `;
+        return this.client.query(query, { first, where });
+    }
+    async listPlans(opts = {}) {
+        const { first = 25, where, orderBy } = opts;
+        const query = `
+      query ListPlans($first: Int!, $where: QueryNervousSystemPlansWhereWhereConditions, $orderBy: [QueryNervousSystemPlansOrderByOrderByClause!]) {
+        nervousSystemPlans(first: $first, where: $where, orderBy: $orderBy) {
+          data { ${PLAN_LIST_FIELDS} }
+          paginatorInfo { currentPage lastPage total }
+        }
+      }
+    `;
+        return this.client.query(query, { first, where, orderBy });
+    }
+    async getPlan(id) {
+        const query = `
+      query GetPlan($id: ID!) {
+        nervousSystemPlan(id: $id) {
+          ${PLAN_DETAIL_FIELDS}
+        }
+      }
+    `;
+        return this.client.query(query, { id });
+    }
+    async getAgentCapabilities(agentId, framework) {
+        const query = `
+      query AgentCapabilities($agent_id: ID!, $framework: String) {
+        nervousSystemAgentCapabilities(agent_id: $agent_id, framework: $framework) {
+          skills {
+            id name description skill_type version is_active
+          }
+          tools {
+            id name description tool_type requires_permission version is_active
+          }
+        }
+      }
+    `;
+        return this.client.query(query, { agent_id: agentId, framework });
+    }
+    // ── Plan mutations ─────────────────────────────────────────
+    async createPlan(input) {
+        const mutation = `
+      mutation CreatePlan($input: CreateNervousSystemPlanInput!) {
+        createNervousSystemPlan(input: $input) {
+          ${PLAN_DETAIL_FIELDS}
+        }
+      }
+    `;
+        return this.client.query(mutation, { input });
+    }
+    async updatePlan(id, input) {
+        const mutation = `
+      mutation UpdatePlan($id: ID!, $input: UpdateNervousSystemPlanInput!) {
+        updateNervousSystemPlan(id: $id, input: $input) {
+          ${PLAN_DETAIL_FIELDS}
+        }
+      }
+    `;
+        return this.client.query(mutation, { id, input });
+    }
+    async approvePlan(id, input) {
+        const mutation = `
+      mutation ApprovePlan($id: ID!, $input: ApproveNervousSystemPlanInput!) {
+        approveNervousSystemPlan(id: $id, input: $input) {
+          id
+          status
+          requires_human_approval
+          approved_at
+          review_outcome
+          approver { id firstname lastname }
+        }
+      }
+    `;
+        return this.client.query(mutation, { id, input });
+    }
+    async deletePlan(id) {
+        const mutation = `
+      mutation DeletePlan($id: ID!) {
+        deleteNervousSystemPlan(id: $id)
+      }
+    `;
+        return this.client.query(mutation, { id });
+    }
+    // ── Task mutations ─────────────────────────────────────────
+    async addTask(planId, input) {
+        const mutation = `
+      mutation AddTask($plan_id: ID!, $input: NervousSystemTaskInput!) {
+        addTaskToNervousSystemPlan(plan_id: $plan_id, input: $input) {
+          ${TASK_FIELDS}
+        }
+      }
+    `;
+        return this.client.query(mutation, { plan_id: planId, input });
+    }
+    async updateTaskStatus(id, input) {
+        const mutation = `
+      mutation UpdateTaskStatus($id: ID!, $input: UpdateNervousSystemTaskStatusInput!) {
+        updateNervousSystemTaskStatus(id: $id, input: $input) {
+          ${TASK_FIELDS}
+        }
+      }
+    `;
+        return this.client.query(mutation, { id, input });
+    }
+    async deleteTask(id) {
+        const mutation = `
+      mutation DeleteTask($id: ID!) {
+        deleteNervousSystemTask(id: $id)
+      }
+    `;
+        return this.client.query(mutation, { id });
+    }
+}

package/dist/domains/nervousSystem/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -7,6 +7,7 @@ import { SocialService } from "./domains/social/index.js";
 import { EcosystemService } from "./domains/ecosystem/index.js";
 import { DealsService } from "./domains/deals/index.js";
 import { EventsService } from "./domains/events/index.js";
+import { NervousSystemService } from "./domains/nervousSystem/index.js";
 import { registerCrmTools } from "./tools/crm.js";
 import { registerInventoryTools } from "./tools/inventory.js";
 import { registerOrdersTools } from "./tools/orders.js";
@@ -14,6 +15,7 @@ import { registerSocialTools } from "./tools/social.js";
 import { registerEcosystemTools } from "./tools/ecosystem.js";
 import { registerDealsTools } from "./tools/deals.js";
 import { registerEventsTools } from "./tools/events.js";
+import { registerNervousSystemTools } from "./tools/nervousSystem.js";
 import { toolResult } from "./tools/helpers.js";
 const DEFAULT_API_URL = "https://graphapi.kanvas.dev/graphql";
 // OpenClaw v2026.4.5+ calls register() per-agent-context (main, subagents,
@@ -29,6 +31,7 @@ let sharedSocial = null;
 let sharedEcosystem = null;
 let sharedDeals = null;
 let sharedEvents = null;
+let sharedNervousSystem = null;
 let startupBannerShown = false;
 let skipBannerShown = false;
 function resolveConfig(pluginConfig) {
@@ -123,6 +126,7 @@ export default {
             sharedEcosystem = new EcosystemService(sharedClient);
             sharedDeals = new DealsService(sharedClient);
             sharedEvents = new EventsService(sharedClient);
+            sharedNervousSystem = new NervousSystemService(sharedClient);
         }
         // Tools and hooks must be registered on every api object — each one is
         // a separate agent context (main, subagents, cron lanes).
@@ -134,6 +138,7 @@ export default {
         registerEcosystemTools(api, sharedEcosystem, ensureAuth);
         registerDealsTools(api, sharedDeals, ensureAuth);
         registerEventsTools(api, sharedEvents, ensureAuth);
+        registerNervousSystemTools(api, sharedNervousSystem, ensureAuth);
         api.registerTool({
             name: "kanvas_test_connection",
             label: "Test Connection",
@@ -158,7 +163,7 @@ export default {
         }, { commands: ["setup"] });
         if (!startupBannerShown) {
             startupBannerShown = true;
-            api.logger.info("Kanvas plugin registered — 73 tools loaded");
+            api.logger.info("Kanvas plugin registered — 84 tools loaded");
         }
     },
 };
@@ -279,6 +284,21 @@ Use when the user asks about companies, branches/locations, user management, rol
 - \`kanvas_assign_role_to_user\` → assign roles (e.g. super admin). Call \`kanvas_list_roles\` first to get role IDs.
 - \`kanvas_remove_role_from_user\` → remove a role from a user
 
+**Nervous System (Plans, Tasks, Activities)**
+This is how humans assign work to you. Read the \`nervous-system-working\` skill for the full protocol. Treat every non-trivial request as a Plan; plan first, execute second. Move statuses deliberately — humans watch the kanban.
+- \`kanvas_list_my_plans\` → find work assigned to you (filter by statuses: draft/awaiting_approval/active/blocked)
+- \`kanvas_get_plan\` → full plan detail (description, input, tasks, files, parent)
+- \`kanvas_create_plan\` → create plan or sub-plan, optionally with seeded tasks
+- \`kanvas_update_plan\` → transition status (draft→active→done/blocked/failed), set output JSON, attach files
+- \`kanvas_approve_plan\` → approve/reject a plan in awaiting_approval
+- \`kanvas_add_task\` → append a task to the checklist (sequence determines order)
+- \`kanvas_update_task_status\` → pending → in_progress → done (or blocked/failed)
+- \`kanvas_list_agent_capabilities\` → list skills/tools granted to an agent
+- \`kanvas_delete_plan\` / \`kanvas_delete_task\` → delete
+- For Activities (the conversation channel), use \`kanvas_create_message\` with \`channel_slug = plan.uuid\` and \`message_verb: "comment"\`. Read with \`kanvas_list_channel_messages\` using the same slug.
+- **Always re-read the channel** before acting on a plan you've worked on before.
+- **Never act** on a plan with \`requires_human_approval=true\` until it's flipped to active.
+
 **Diagnostics**
 - \`kanvas_test_connection\` → verify the API is reachable
 

package/dist/tools/nervousSystem.js

@@ -0,0 +1,217 @@
+import { Type } from "@sinclair/typebox";
+import { toolResult } from "./helpers.js";
+const TaskInputSchema = Type.Object({
+    title: Type.String({ description: "Task title (verb phrase, e.g. 'Crawl /features')" }),
+    sequence: Type.Optional(Type.Number({ description: "Execution order (0, 1, 2...)" })),
+    description: Type.Optional(Type.String()),
+    status: Type.Optional(Type.String({ description: "pending | in_progress | blocked | done | failed | cancelled" })),
+    result: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+    blocked_reason: Type.Optional(Type.String()),
+});
+const FilesInputSchema = Type.Array(Type.Object({
+    url: Type.String({ description: "Public URL of the file" }),
+    name: Type.String({ description: "Display name" }),
+    field_name: Type.Optional(Type.String()),
+}), { description: "Files to attach (appended, not replaced)" });
+const PlanStatusSchema = Type.String({
+    description: "Plan status: draft | awaiting_approval | active | blocked | done | failed | cancelled",
+});
+const TaskStatusSchema = Type.String({
+    description: "Task status: pending | in_progress | blocked | done | failed | cancelled",
+});
+export function registerNervousSystemTools(api, service, ensureAuth) {
+    // ── Read ───────────────────────────────────────────────────
+    api.registerTool({
+        name: "kanvas_list_my_plans",
+        label: "List My Plans",
+        description: "List nervous-system plans assigned to an agent. Filter by statuses to see open work " +
+            "(e.g. ['draft','awaiting_approval','active','blocked']). Returns plans ordered by priority desc, deadline asc.",
+        parameters: Type.Object({
+            agent_id: Type.Union([Type.String(), Type.Number()], { description: "The agent's ID" }),
+            statuses: Type.Optional(Type.Array(Type.String(), {
+                description: "Statuses to include. Default: all.",
+            })),
+            first: Type.Optional(Type.Number({ description: "Max results (default 50)" })),
+        }),
+        async execute(_id, params) {
+            await ensureAuth();
+            return toolResult(await service.listMyPlans(params));
+        },
+    });
+    api.registerTool({
+        name: "kanvas_list_plans",
+        label: "List Plans (admin)",
+        description: "List nervous-system plans with arbitrary where filters. Allowed where columns: " +
+            "ID, UUID, AGENT_ID, USERS_ID, ENTITY_NAMESPACE, ENTITY_ID, PLAN_TYPE, STATUS, PRIORITY, PARENT_PLAN_ID.",
+        parameters: Type.Object({
+            first: Type.Optional(Type.Number({ description: "Max results (default 25)" })),
+            where: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+            orderBy: Type.Optional(Type.Array(Type.Object({
+                column: Type.String(),
+                order: Type.String({ description: "ASC or DESC" }),
+            }))),
+        }),
+        async execute(_id, params) {
+            await ensureAuth();
+            return toolResult(await service.listPlans(params));
+        },
+    });
+    api.registerTool({
+        name: "kanvas_get_plan",
+        label: "Get Plan",
+        description: "Get full plan detail: description, input/output, tasks, files, tags, agent, user, parent, completion %.",
+        parameters: Type.Object({
+            id: Type.String({ description: "Plan ID" }),
+        }),
+        async execute(_id, params) {
+            await ensureAuth();
+            return toolResult(await service.getPlan(params.id));
+        },
+    });
+    api.registerTool({
+        name: "kanvas_list_agent_capabilities",
+        label: "List Agent Capabilities",
+        description: "List the skills and tools an agent has been granted. Use this to verify you can do something before agreeing to a plan.",
+        parameters: Type.Object({
+            agent_id: Type.String({ description: "Agent ID" }),
+            framework: Type.Optional(Type.String({ description: "Framework filter (optional)" })),
+        }),
+        async execute(_id, params) {
+            await ensureAuth();
+            return toolResult(await service.getAgentCapabilities(params.agent_id, params.framework));
+        },
+    });
+    // ── Plan write ─────────────────────────────────────────────
+    api.registerTool({
+        name: "kanvas_create_plan",
+        label: "Create Plan",
+        description: "Create a nervous-system plan (or sub-plan when parent_plan_id is provided). " +
+            "Include a tasks array to seed the checklist on creation. For sensitive work, set requires_human_approval=true " +
+            "to gate the plan in awaiting_approval status until a human approves.",
+        parameters: Type.Object({
+            title: Type.String(),
+            plan_type: Type.String({ description: 'e.g. "data_migration", "outreach", "report_generation"' }),
+            description: Type.Optional(Type.String()),
+            agent_id: Type.Optional(Type.Number()),
+            users_id: Type.Optional(Type.Number()),
+            parent_plan_id: Type.Optional(Type.Number()),
+            entity_namespace: Type.Optional(Type.String({ description: "FQCN of the related entity (e.g. App\\\\Models\\\\Lead)" })),
+            entity_id: Type.Optional(Type.Number()),
+            status: Type.Optional(PlanStatusSchema),
+            priority: Type.Optional(Type.Number({ description: "Higher = more important" })),
+            deadline_at: Type.Optional(Type.String({ description: "ISO datetime" })),
+            input: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+            output: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+            confidence_score: Type.Optional(Type.Number()),
+            requires_human_approval: Type.Optional(Type.Boolean()),
+            tasks: Type.Optional(Type.Array(TaskInputSchema)),
+            files: Type.Optional(FilesInputSchema),
+        }),
+        async execute(_id, params) {
+            await ensureAuth();
+            return toolResult(await service.createPlan(params));
+        },
+    });
+    api.registerTool({
+        name: "kanvas_update_plan",
+        label: "Update Plan",
+        description: "Update a plan's status, title, description, output, or attach files. " +
+            "Use status transitions to signal progress: draft→active to start, active→blocked when stuck, active→done/failed when finished.",
+        parameters: Type.Object({
+            id: Type.String({ description: "Plan ID" }),
+            title: Type.Optional(Type.String()),
+            description: Type.Optional(Type.String()),
+            status: Type.Optional(PlanStatusSchema),
+            priority: Type.Optional(Type.Number()),
+            deadline_at: Type.Optional(Type.String()),
+            input: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+            output: Type.Optional(Type.Record(Type.String(), Type.Unknown()), {
+                description: "Final output JSON (set this before flipping to done)",
+            }),
+            confidence_score: Type.Optional(Type.Number()),
+            requires_human_approval: Type.Optional(Type.Boolean()),
+            files: Type.Optional(FilesInputSchema),
+        }),
+        async execute(_id, params) {
+            await ensureAuth();
+            const { id, ...input } = params;
+            return toolResult(await service.updatePlan(id, input));
+        },
+    });
+    api.registerTool({
+        name: "kanvas_approve_plan",
+        label: "Approve Plan",
+        description: "Approve or reject a plan that is in awaiting_approval status. Approving flips it to active; rejecting flips it to cancelled.",
+        parameters: Type.Object({
+            id: Type.String({ description: "Plan ID" }),
+            approved: Type.Boolean({ description: "true to approve, false to reject" }),
+            review_outcome: Type.Optional(Type.String({ description: "Optional reviewer note" })),
+        }),
+        async execute(_id, params) {
+            await ensureAuth();
+            return toolResult(await service.approvePlan(params.id, {
+                approved: params.approved,
+                review_outcome: params.review_outcome,
+            }));
+        },
+    });
+    api.registerTool({
+        name: "kanvas_delete_plan",
+        label: "Delete Plan",
+        description: "Delete a plan by ID.",
+        parameters: Type.Object({
+            id: Type.String({ description: "Plan ID" }),
+        }),
+        async execute(_id, params) {
+            await ensureAuth();
+            return toolResult(await service.deletePlan(params.id));
+        },
+    });
+    // ── Task write ─────────────────────────────────────────────
+    api.registerTool({
+        name: "kanvas_add_task",
+        label: "Add Task to Plan",
+        description: "Append a task to a plan's checklist. Sequence determines execution order (0, 1, 2...).",
+        parameters: Type.Object({
+            plan_id: Type.String({ description: "Plan ID" }),
+            title: Type.String({ description: "Task title (verb phrase)" }),
+            sequence: Type.Optional(Type.Number()),
+            description: Type.Optional(Type.String()),
+            status: Type.Optional(TaskStatusSchema),
+        }),
+        async execute(_id, params) {
+            await ensureAuth();
+            const { plan_id, ...input } = params;
+            return toolResult(await service.addTask(plan_id, input));
+        },
+    });
+    api.registerTool({
+        name: "kanvas_update_task_status",
+        label: "Update Task Status",
+        description: "Move a task through its lifecycle: pending → in_progress → done (or blocked/failed/cancelled). " +
+            "Set 'result' as JSON when done; set 'blocked_reason' when blocked.",
+        parameters: Type.Object({
+            id: Type.String({ description: "Task ID" }),
+            status: TaskStatusSchema,
+            result: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+            blocked_reason: Type.Optional(Type.String()),
+        }),
+        async execute(_id, params) {
+            await ensureAuth();
+            const { id, ...input } = params;
+            return toolResult(await service.updateTaskStatus(id, input));
+        },
+    });
+    api.registerTool({
+        name: "kanvas_delete_task",
+        label: "Delete Task",
+        description: "Delete a task by ID.",
+        parameters: Type.Object({
+            id: Type.String({ description: "Task ID" }),
+        }),
+        async execute(_id, params) {
+            await ensureAuth();
+            return toolResult(await service.deleteTask(params.id));
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kanvas/openclaw-plugin",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Connects agents to Kanvas — your company's nervous system for CRM, inventory, orders, and messaging.",
   "license": "MIT",
   "repository": {

package/skills/kanvas-nervous-system/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: nervous-system-working
+description: How an agent finds work assigned to it, plans the work as a checklist, executes it task by task, asks humans for approval when required, and leaves comments to communicate. Use this skill any time the agent is asked to "do" something for a user or company — the work belongs in a Plan, the steps belong in Tasks, and the conversation belongs in the Activities channel. Triggers on phrases like "find my work", "what do I have to do", "I need to plan this", "can you do X", "block until human approves", "leave a note for the user", "I'm stuck and need help".
+metadata: {"openclaw":{"requires":{"config":["plugins.entries.kanvas"]}}}
+---
+
+# Working in the Nervous System (Plans, Tasks, Activities)
+
+You're an agent inside Kanvas. Humans and other systems assign work to you through a structured object called a **Plan**. A Plan is your "issue ticket" — what you're being asked to do, broken down into Tasks (a checklist), with files attached, tags applied, and an Activities channel where you talk to the humans involved.
+
+Treat every non-trivial request as a Plan: **plan first, execute second**. When in doubt, *write the checklist down* (as Tasks) before doing the work. This is how humans see what you're doing and trust you.
+
+## The shape of your work
+
+```
+Plan ─┬─ Tasks (the checklist of steps)
+      ├─ Activities channel (where you talk to humans)
+      ├─ Files (mockups, screenshots, attachments)
+      ├─ Tags (urgent, design-review, etc.)
+      └─ Status (draft → active → done | blocked | failed | cancelled)
+```
+
+The status determines which kanban column the human sees you in. Move it deliberately.
+
+| Status | Meaning | When to be in it |
+|---|---|---|
+| `draft` | You're still figuring out the plan / haven't started | Right after creation, before you've written tasks |
+| `awaiting_approval` | The plan needs a human review before you act | Set automatically when `requires_human_approval=true` |
+| `active` | You're working on it right now | After you've claimed it and started executing |
+| `blocked` | You can't proceed without input | Stuck on a question, missing data, external dependency |
+| `done` | All tasks completed successfully | Final, terminal — celebrate |
+| `failed` | You tried, you can't finish, the human needs to know | Final, terminal — leave a comment explaining what broke |
+| `cancelled` | Someone (human or you) decided this shouldn't happen | Final, terminal |
+
+---
+
+## 1. Find work assigned to you
+
+You have an `agent_id`. Use `kanvas_list_my_plans` to list everything you've been asked to do, filtered to the open statuses:
+
+```
+kanvas_list_my_plans({ agent_id: <me>, statuses: ["draft", "awaiting_approval", "active", "blocked"] })
+```
+
+**Heuristics for picking what to do next:**
+1. Anything with `status='blocked'` and a recent comment from a human → unblock it first. They were waiting on you.
+2. Then anything `awaiting_approval` that the user just approved (re-list, you'll find it `active` now) → start executing.
+3. Then `active` plans you've already started — finish them, don't fan out.
+4. Only after that, pick up new `draft` work. Higher `priority` first; closer `deadline_at` next.
+
+Do **not** start a plan whose `requires_human_approval = true` and `status = awaiting_approval`. Wait for a human to flip it to `active` via the approve mutation.
+
+---
+
+## 2. Read the plan thoroughly before acting
+
+Before you do anything, fetch full detail with `kanvas_get_plan({ id })` and **read everything**.
+
+The fields that matter most for your decisions:
+- **`description`** — the human's brief. Usually free-text. Read it.
+- **`input`** — structured payload (JSON). Often contains parameters, IDs, prior context. **Always check it.**
+- **`tasks`** — if a human pre-loaded a checklist, follow it. If empty, you should create one (see §3).
+- **`entity_namespace` + `entity_id`** — the plan is *about* a specific entity (e.g. a Lead, a Deal, a Project). Fetch that entity's detail too.
+- **`files`** — mockups, screenshots, references. Don't ignore them.
+- **`parent`** — if non-null, this is a sub-plan. Look at the parent for upstream context.
+- **`tags`** — surface hints from the human (`urgent`, `legal-review-needed`, etc.).
+
+If you don't understand the brief after reading all of this, **don't guess**. Leave a comment on the Activities channel asking for clarification and transition to `blocked` (see §6).
+
+Also re-read the plan's Activities messages with `kanvas_list_channel_messages({ channel_slug: <plan.uuid>, first: 20 })`. **Read the latest messages every time you re-enter a plan.** A human may have answered a question, redirected the work, or cancelled the plan since your last action.
+
+---
+
+## 3. Plan first — write the tasks down
+
+If the plan has no tasks (or only one vague task), break it into a real checklist before executing. **The checklist is the contract** — the human sees it on the kanban card and watches you work through it.
+
+Two ways to add tasks:
+
+- **At plan creation** (`kanvas_create_plan` with a `tasks: [...]` array) — recommended.
+- **On an existing plan**: `kanvas_add_task({ plan_id, title, sequence, status: "pending" })`
+
+**Sequence matters** — lower `sequence` runs first. Use 0, 1, 2… in execution order.
+
+**Granularity:** tasks should be 5–60 minutes of work each. Too coarse and humans can't see progress; too fine and the kanban gets noisy. If in doubt, prefer fewer + slightly bigger tasks — you can always add more later.
+
+**Names should be verbs**: "Crawl /features", "Edit demo video", "Email Maria about objection". Not "Step 1" or "Crawling".
+
+Once tasks are in place, transition the plan to `active`:
+
+```
+kanvas_update_plan({ id, status: "active" })
+```
+
+This stamps `started_at` on the backend automatically — you don't pass it.
+
+---
+
+## 4. Execute task by task
+
+For each task, in sequence order:
+
+1. **Mark it `in_progress`:**
+   ```
+   kanvas_update_task_status({ id, status: "in_progress" })
+   ```
+   Only one task should be `in_progress` at a time.
+
+2. **Do the work.** Use whatever tools you have. Output should be captured in `result` if it's structured (an artifact reference, a JSON record, etc.).
+
+3. **Mark it `done`:**
+   ```
+   kanvas_update_task_status({ id, status: "done", result: { ... } })
+   ```
+   The plan's `completion_pct` recomputes automatically.
+
+4. **Loop** to the next pending task.
+
+When you transition a task, the system emits a ledger event AND a Pusher broadcast — humans watching the kanban see your progress in real time. **You don't need to do anything extra to "notify" them**; status transitions are the notification.
+
+---
+
+## 5. Add files / artifacts as you produce them
+
+If a task produces an artifact (a generated image, a CSV, a report), attach it to the plan:
+
+```
+kanvas_update_plan({ id, files: [{ url: "...", name: "..." }] })
+```
+
+Files are appended (not replaced). Humans see them on the ticket detail's right-hand panel and in any UI rendering `plan.files`.
+
+---
+
+## 6. Talk to humans through the Activities channel
+
+Every plan has a Social Channel named `"Activities"` with `slug = plan.uuid`. This is your conversation thread with the humans on the ticket. Use it to:
+
+- **Report progress on something interesting** ("I found 14 broken links — 3 in /features, 11 in /docs. Continuing.")
+- **Ask a question when stuck** ("The brief says 'short demo' — should I cap at 60s or 90s?")
+- **Surface a finding worth a human glance** ("The Lead's email bounced — flagged it on the lead record. Should I keep going with SMS or pause?")
+- **Announce blockers** *before* you flip to `blocked` so humans can pre-empt the wait
+
+**Posting a comment** uses the existing message tool with the plan's UUID as the channel slug:
+
+```
+kanvas_create_message({
+  message_verb: "comment",
+  message: { text: "..." },
+  channel_slug: <plan.uuid>,
+  is_public: 1
+})
+```
+
+**Reading messages**:
+
+```
+kanvas_list_channel_messages({ channel_slug: <plan.uuid>, first: 50 })
+```
+
+### Tone for comments
+
+- Concise. One paragraph max.
+- State the observation, then the implication, then the proposed next step.
+- Don't apologize, don't pad. "Email bounced. Pausing outreach. Open: try SMS, or close as bad-contact?" beats "Hi! I noticed that unfortunately the email seems to have bounced..."
+- If you're asking a question, put it on the last line, single sentence.
+
+---
+
+## 7. Approval gates — when humans must say yes first
+
+If a plan has `requires_human_approval = true`, the system creates it with `status = awaiting_approval`. You must **not** execute its tasks until a human flips it to `active`.
+
+You can:
+- Read the plan to understand what's being requested
+- Add tasks to flesh out your proposed approach (this signals to the human what you intend to do)
+- Leave a comment on the Activities channel explaining your plan and asking for approval
+
+You **cannot**:
+- Move tasks to `in_progress`
+- Move the plan to `active` yourself
+- Take any side-effecting action
+
+When the human approves (via `kanvas_approve_plan`), the plan flips to `active`. If they deny, it flips to `cancelled`.
+
+---
+
+## 8. When stuck — block the plan, don't fail it
+
+You'll hit cases where you can't proceed without input. **Block the plan, don't fail it.** Failing is for "I tried and broke things"; blocking is for "I'm waiting on something."
+
+```
+kanvas_update_task_status({ id, status: "blocked", blocked_reason: "..." })
+kanvas_update_plan({ id, status: "blocked" })
+```
+
+**Always pair the block with a comment** on the Activities channel explaining what you need. The blocked status alone is opaque; the comment is what unblocks you.
+
+Bad: silent block. The human sees red on the kanban with no context.
+Good: block + comment ("Blocked — need the API key for SendGrid. The one in the input expired yesterday.").
+
+When the human resolves the block, they'll either reply on the channel or update the plan/task status. **Re-read the channel before acting.**
+
+---
+
+## 9. Sub-plans — when a task is too big
+
+If during execution a task turns out to be a substantial sub-project (5+ steps of its own), don't try to do it inline. Create a **child plan**:
+
+```
+kanvas_create_plan({
+  title: "Migrate the 8000 legacy contacts",
+  plan_type: "data_migration",
+  parent_plan_id: 127,
+  agent_id: <me>,
+  status: "draft",
+  tasks: [
+    { title: "Profile the source schema", sequence: 0 },
+    { title: "Map fields to target schema", sequence: 1 }
+  ]
+})
+```
+
+The parent task that spawned this can transition to `done` immediately (your work is to start the sub-plan, not finish the migration personally), or to `in_progress` (waiting on the sub-plan to finish). Use whichever matches the human's expectation — when in doubt, leave a comment.
+
+---
+
+## 10. Finishing — done vs. failed vs. cancelled
+
+When all tasks are `done`:
+
+```
+kanvas_update_plan({
+  id,
+  status: "done",
+  output: {
+    summary: "...",
+    artifacts: [...],
+    metrics: { ... }
+  }
+})
+```
+
+Set a useful `output` — a JSON summary of what was produced. Humans use this without re-reading the whole task list.
+
+If something genuinely broke and a human needs to take over:
+
+```
+kanvas_update_plan({
+  id,
+  status: "failed",
+  output: { summary: "Couldn't proceed. Reason and recovery suggestion in the Activities channel." }
+})
+```
+
+**Always pair `failed` with a comment** explaining what broke and what you tried. "It didn't work" is not an acceptable terminal state.
+
+---
+
+## 11. Pre-emptive comments — don't wait to be asked
+
+When something *interesting* happens — even if not blocking — a short comment is almost always worth it. The human's mental model of you depends on these comments:
+
+- "Found that the lead's CRM record disagrees with the form submission on `phone`. Going with the form value since it's more recent."
+- "Switched from `gpt-4` to `claude-sonnet-4-7` mid-run because the JSON output kept malforming. Re-running task 3."
+- "The deadline is in 4 hours, this will likely take 6. Want to deprioritize task 5 (nice-to-have) to fit?"
+
+Three rules of thumb:
+1. If you made a non-obvious decision the human couldn't have predicted from the brief → comment.
+2. If you're going to run for more than ~10 minutes without a status change → comment progress.
+3. If your confidence on the outcome is < 70% → comment what your confidence is and why.
+
+---
+
+## 12. Meta — when to refuse
+
+Some things you should not do, even if assigned:
+
+- **Destructive actions on data you don't own** — if the plan asks you to "delete all leads from before 2024" and you have no signed-off retention policy, *block + comment*. Don't ship destruction silently.
+- **Workflows that move money / send to many recipients without approval gating** — even if `requires_human_approval=false`, if the action's blast radius is high, switch the plan to `awaiting_approval` yourself by setting `requires_human_approval=true` and `status=awaiting_approval`, and leave a comment explaining why.
+- **Anything outside your declared skills/tools** — your `kanvas_list_agent_capabilities` tool tells you what you're allowed to do. If a task requires something not in your grants, *block + comment* asking for the grant.
+
+Better to ask once than apologize a hundred times.
+
+---
+
+## 13. Summary checklist for every plan you touch
+
+- [ ] Read the full plan including `input`, `description`, attached files, and the **last 10 messages** on the Activities channel (`kanvas_list_channel_messages`)
+- [ ] Verify your skills/tools cover what's needed (`kanvas_list_agent_capabilities`)
+- [ ] If no tasks, write the checklist before doing anything (`kanvas_add_task` or include in `kanvas_create_plan`)
+- [ ] If `requires_human_approval=true`, **don't act** — leave a comment with your proposed approach and wait
+- [ ] Move tasks `pending → in_progress → done` one at a time, in sequence order
+- [ ] Comment when something non-obvious happens
+- [ ] Block + comment if you can't proceed
+- [ ] Set a useful `output` JSON before flipping to `done`
+- [ ] Don't refuse silently — if you won't do something, leave a comment explaining why
+
+---
+
+## Reference — the Kanvas tools you'll use
+
+| What you want to do | Tool |
+|---|---|
+| Find work assigned to me | `kanvas_list_my_plans` |
+| Read full plan context | `kanvas_get_plan` |
+| Create a new plan (or sub-plan) | `kanvas_create_plan` |
+| Add a task | `kanvas_add_task` |
+| Start / finish / block a task | `kanvas_update_task_status` |
+| Start / block / fail / done a plan | `kanvas_update_plan` |
+| Approve / reject a plan | `kanvas_approve_plan` |
+| Delete a plan or task | `kanvas_delete_plan` / `kanvas_delete_task` |
+| Read messages on the Activities channel | `kanvas_list_channel_messages({ channel_slug: <plan.uuid> })` |
+| Post a comment | `kanvas_create_message({ channel_slug: <plan.uuid>, message_verb: "comment", message, is_public: 1 })` |
+| List my granted capabilities | `kanvas_list_agent_capabilities` |
+
+If a tool doesn't exist for what you need to do, that's a signal — comment on the Activities channel that you need the human to grant you a new capability or assign the task to a different agent.