todo-handling

Todo Handling Skill

Use this skill for deliberately authored, durable work ownership and status tracking. Todos are the live company ledger; Workflows are the reusable HOW. Search before creating a duplicate. A Workflow invocation never creates, links, transitions, approves, or mutates a Todo.

Find the right Todo

• Use list_work_items for recent work or structured filters such as status, source, assignee, department, and needsAttentionFor.
• Use search_work_items when you have text or several filters. It requires at least one real filter.
• Use get_work_item before changing a Todo so you understand its acceptance criteria, assignee, source/provenance, verification policy, and current status.

The statuses are backlog, assigned, executing, in_review, done, blocked, escalated, and cancelled. Agent updates intentionally expose only in_review, blocked, escalated, and done; other lifecycle decisions stay on their owning surface.

Create and assign

Create a Todo only for durable work that needs an owner or review trail:

{
  "title": "Verify release candidate",
  "body": "Run the release checks and attach the evidence.",
  "acceptance": "Typecheck, tests, lint, and build pass with command output.",
  "assignee": "a-reviewer",
  "department": "engineering",
  "verifyPolicy": {
    "mode": "verify",
    "verifier": { "employee": "a-lead" },
    "maxRounds": 4
  }
}

1. Search for an existing item covering the same outcome.
2. Call create_work_item with a concise title, enough context to act, and testable acceptance criteria.
3. Use assign_work_item when assignment was not supplied or must change. Verify the employee with get_employee or find_employees first.
4. Use delegate_task instead when the assignee should start immediately; it can use an existing workItemId or create and link a new Todo atomically.

Do not invent provenance or attach approval fields during creation. Each owning company surface records its own source provenance.