todo-handling

name	todo-handling
description	Create, assign, update, review, and archive Jinn Todos through the typed work-item tools

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 list_work_items with rootsOnly: true for an objective-level view, parentId for one Todo's direct children, or rootId for a whole Todo family.
• 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.
• Use get_work_item_tree when the work has child Todos; it returns the nested breakdown and roll-up.

The statuses are backlog, assigned, executing, in_review, done, blocked, escalated, and cancelled. Agent updates reach every status but cancelled, which has no agent tool at all.

Who may move a stopped Todo

done, cancelled, and escalated are sticky: an ordinary agent move does not release them, so work that stopped there stays stopped until someone with standing decides otherwise.

The top-level orchestrator session — the one the operator is talking to, which carries no employee identity of its own — is that someone. It passes asOperator: true to move a stopped Todo back into flow: an escalated Todo whose question the operator has answered in chat, or a closed one being reopened. The audit event then records the operator as the actor, names the calling session under asOperator, and keeps the note, so the instruction behind the move is on the record. Put the operator's actual instruction in that note.

Every other session is refused, by name: an employee, and anything an employee spawns. Three guards hold for everyone, the orchestrator included — an approval routed to the operator still refuses an agent decider, a producer still cannot close its own work (done belongs to the reviewer), and closing a Todo's open descendants along with it stays on the human surface.

Shape the hierarchy

One operator outcome should normally map to one root Todo. A checklist does not imply one Todo per item. Keep procedural steps, commands, and release checklists in the root Todo body, comments, or session activity.

Only independently assignable or independently reviewable deliverables become child Todos. Create child Todos with parentId:

{
  "title": "Verify release artifacts",
  "parentId": "ACM-42",
  "acceptance": "Checks pass and evidence is attached."
}

If another skill asks for one Todo per checklist step, use engine-local progress tracking unless each step passes this durable-work boundary. This Jinn Todo doctrine governs the company ledger. Keep trees shallow and outcome-shaped; do not turn implementation procedures into ledger clutter.

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.",
  "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. Call assign_work_item next: creation never carries an assignee, so assignment is always its own second call. 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.

Approval flow

Approvals are routed records on a Todo, separate from its lifecycle status. Generic update_work_item does not perform approval decisions or review-bounce accounting; never use it as a substitute while an approval is pending.

1. The Todo owner or linked execution session, its manager, or the COO requests a decision with request_work_item_approval:

{
  "id": "wi_example",
  "request": "Do the verification artifacts satisfy the acceptance criteria?"
}

Omit target to use the default routed manager/COO. Repeating the identical pending request with the same target is idempotent and does not append another approval-requested event. A changed request or target replaces the pending route; there is no self-declared approval state on create_work_item.

Set operatorOnly: true to reserve the gate for the human operator when the decision authorizes something irreversible. No employee can then decide it, including the COO and including after an escalation, and the escalation itself is refused. It cannot be combined with target.

2. The routed manager/COO decides with decide_work_item_approval and an optional evidence note:

{
  "id": "wi_example",
  "decision": "approve",
  "note": "Acceptance checks and artifacts verified."
}

The resolved routed owner cannot decide their own approval, but an employee hierarchy root/COO is exempt from that enforcement check. Linked execution alone is not checked, so routed managers/COO should avoid approving work they personally executed and use another authorized reviewer when possible. For a native approval on an in_review Todo, approve atomically records the decision and moves the Todo to done. reject records the critique, returns it to executing, and increments rounds; when the increment reaches verifyPolicy.maxRounds, it moves to escalated instead. Without an explicit limit, the effective ceilings are 2 rounds for trust/verify and 3 for thorough. On another status, the decision is recorded but status stays unchanged.

3. After a rejection, the worker revises the work, uses update_work_item to return it to in_review, and calls request_work_item_approval again for the next bounded review. Do not create a duplicate Todo.

4. If the routed manager/COO deliberately needs operator/aCEO authority, call escalate_work_item_approval with the pending Todo id and an optional reason. Escalation exposes the pending approval to that path; it does not approve or reject it.

Todo approvals affect only the Todo. Workflow operations never mutate Todos. A Todo-status trigger is a one-way input; the resulting Workflow run is independent.

Keep status honest

• Worker finished and ready for review: update_work_item to in_review with a note naming artifacts, checks, and remaining risks.
• Cannot proceed without an external change: move to blocked and state the concrete blocker plus what would unblock it.
• A non-approval manager/operator decision is required: move to escalated and summarize the options and recommendation. For a pending approval, use escalate_work_item_approval instead.
• Reviewer accepts ungated work: move it to done with verification evidence. If an approval is pending, use decide_work_item_approval instead so the Todo approval consequence is recorded atomically.
• Never mark your own produced work done; the reviewer owns completion. Do not use done to hide partial work or a failed verification.

Example:

{
  "id": "wi_example",
  "status": "in_review",
  "note": "Implemented the requested change; typecheck, tests, lint, and build are green. Evidence is attached to the child session."
}

Use archive_work_item for obsolete or historical clutter while preserving its row and audit trail. Cancellation is a human lifecycle decision, not an agent status shortcut.

Archiving a Todo, or delegating onto one that already exists, asks for standing over it: its owner, that owner's manager, or the org root. The top-level orchestrator session holds that standing over any Todo despite having no employee identity, so it does not need a workaround to tidy the ledger. A session spawned beneath it does not inherit it.

Review loop

1. Reviewer calls get_work_item and inspects the linked execution session plus any separately supplied evidence.
2. If the Todo has a pending approval, use decide_work_item_approval; approve or reject with a precise evidence note.
3. After a rejection, the worker revises, returns the Todo to in_review, and requests the next approval. The rejection path increments rounds and auto-escalates when the effective limit is reached.
4. Use escalate_work_item_approval before the round cap only when the routed approver needs an operator/aCEO decision.

Report Todo id, title, assignee, status, verification result, and next owner. Do not create a second Todo merely because the first is blocked or under review.