Tasks

Tasks

Use this skill to drive the workspace Kanban end-to-end. Tasks are durable board items with owner, priority, schedule, and conversation linkage. Every operation goes through the cloud task CLI — never reply that a task was created/moved/completed unless the command actually returned a task ID and status.

⛔ Hard rules — delegation discipline

When the user asks you to assign / delegate / hand off work to ANOTHER agent (e.g. "create kanban tasks and assign to @research-agent", "give this to Bob"):

1. Call cloud task create --assignee-name <agent> (or --assignee-id). That is the ONLY legitimate delegation path. A delegation is a tracked board card that ALSO auto-dispatches: the card shows on the Kanban (留痕/可观测) and the cloud routes it to the target agent's daemon the moment the assignee is set — the target picks it up via its own dispatch loop, no manual "drag to Running" needed. (A --no-card pure run exists for internal orchestrator sub-steps that should NOT surface a card.)
2. For a delegation-only request, stop after reporting the returned IDs / titles. If the user also requested orchestration, follow-through, or result collection, continue read-only status/result collection with bounded waits as described below. Never duplicate the assignee's work yourself.
3. NEVER use a generic Task / subagent / fan-out / parallel-agent tool to silently do the work in-process. That bypasses the kanban board, the assignee never sees the card, the user's mental model ("an agent is working on this") is violated, and the delegation is fake. If you find yourself reaching for any tool whose name is "Task", "Subagent", "Worker", "Fanout", "ParallelAgents", or anything else that spawns an inline executor — stop and re-read this section.
4. The phrase "I've also started working on these" after a cloud task create is a red flag that you violated rule 3. The correct phrase is "Tasks created and assigned. @research-agent will pick up the cards."

This is non-negotiable. Bypassing it makes the agent ecosystem look broken even when the cards are correct, because the user sees the answer come back too fast and notices that the supposed assignee was never @-mentioned in the conversation.

↩️ 结果回流 — 委派后怎么拿到结果（HARD）

委派出去之后，结果不会自动回流到你的对话或 run —— 没有回调、没有自动推送。被派的 agent 在它自己的独立 context 里执行（不进你当前这条会话、也不会在这里发言），产物落在 task 卡 + 看板上。所以：

• 要看结果，你必须主动拉：cloud task get <taskId> 读 status / result / 附件。status=completed 才算交付；review 等你 approve/reject。
• 编排节奏：cloud task create --assignee-name <peer> → 拿到 taskId → 反复 cloud task get <taskId> 直到 status 进终态 → 读产物 → 决定下一步。（有 cloud task wait <id> 时优先用它，省手搓轮询。）
• 「看不到对方回复 ≠ 它没在干」。被派 agent 沉默是正常的——它在独立 context 里跑，结果只在卡上。绝不要因为对话里没动静就自己把活重做一遍（那就是影子执行，违反上面的 Hard rules）。
• 只要求委派时，报 taskId 后结束本轮；明确要求编排/收集结果时，同轮可继续 cloud task get，退避轮询、有超时，不重新执行受派任务。不要自行安排未来轮询或声称已有后台监控。

When to use

• The user asks to create, assign, schedule, or track work ("add to kanban", "give Bob this task", "remind me to ship X by Friday").
• You need to delegate a concrete deliverable to another agent. (See ⛔ rules above.)
• A long-running objective should persist as a workspace goal (kind=goal).
• The user asks about board state ("what's pending", "show me Bob's tasks", "what's blocking the release").
• A task already on the board needs to be updated (priority change, retitle, attach context), completed, approved/rejected in review, or cancelled.
• The task output is a document / deck / spreadsheet / PDF / report. In that case use the office-artifacts skill before completion; a prose-only result is not enough for file-deliverable tasks.

Lifecycle

pending → assigned → running → review → completed | failed | cancelled
              ↑                     ↓
              └──── blocked ────────┤  (unblock returns to assigned)
                                    ↓
                             awaiting_approval
                                    ↓
                        approved / rejected (back to review)

Nine-state lifecycle: pending / assigned / running / review / blocked / awaiting_approval / completed / failed / cancelled. awaiting_approval cards stay visible on the review column — never treat them as gone. blocked has its own column.

A work_item shows on the Kanban; a goal shows on the Goals lane. Filter at list time with --kind work_item,goal if you only want board projection. A delegation (cloud task create --assignee-name …) is a work_item board card that also auto-dispatches (dispatchPolicy=on-assign) — it is BOTH visible on the board AND executing. A work_item you create for a human (or to drive yourself via the UI) stays manual: it only runs on an explicit drag-to-Running. Only globally-visible formal tasks are board cards — a chat @mention is a session-internal run, NOT a board card, and never produces one.

Permission model (v2.0 — release 200 state machine)

The platform enforces a trust-tier × transition matrix (see docs/release200/15-task-state-machine-and-kanban.md §5.2). Each transition's allowed actors are part of the contract; calling outside the matrix returns 403 forbidden with { actorTier, requiredTiers }, and impossible transitions return 409 invalid-transition with { allowedFromHere }.

If you create a task and intend to drive it yourself (no other agent involved), self-assign first: cloud task update <taskId> --assignee-id <your-imUserId>. Otherwise complete and update --progress will both 403.

v2.0 endpoint canonicalisation: every kanban operation (/complete, /approve, /reject, /cancel, drag-to-column, restore-from-cancelled, blocked self-report) is forwarded internally to POST /api/im/tasks/:id/transition. The CLI verbs below are stable; the legacy POST /tasks/:id/{complete,approve,reject,cancel,fail} endpoints carry a Deprecation header but stay functional until 2026-09-01. After that date, scripts hitting the API directly must migrate to /transition; CLI users are insulated.

CLI Reference

Create

# Standard board card
cloud task create \
  --title "Review PR #42" \
  --description "Security check for the auth refactor; ship blocker." \
  --capability code-review \
  --priority high \
  --assignee-id <imUserId>           # or --assignee-name "@alice"
  --conversation-id <convId>          # pin to the session you're in

# Long-running objective (goal lane, not Kanban)
cloud task create --kind goal --title "Reduce p95 latency to <300ms" --priority high

# Scheduled / recurring
cloud task create --title "Daily 9am report" --schedule-cron "0 9 * * *"
cloud task create --title "Run in 2h" --schedule-at "2026-05-19T16:00:00Z"

# Marketplace task with credit escrow
cloud task create --title "Scan deps" --reward 10

Read

cloud task list                                 # YOUR cards (created by or assigned to you)
cloud task list --mine                          # only tasks assigned to YOU (excludes ones you created)
cloud task list --status pending                # your cards, filtered by status
cloud task list --kind work_item,goal           # your cards, board projection only
cloud task list --conversation-id <convId>      # your cards pinned to a conversation
cloud task get <taskId>                          # full detail + logs + runs (a card you have access to)

⚠️ cloud task list is scoped to YOU. As a regular (executor) agent you only ever see cards you created or that are assigned to you — the server enforces this on EVERY filter (you cannot widen it with --kind / --status / --view). You cannot enumerate other roles' cards. This is deliberate: if you can't see someone else's task, you can't accidentally poach it.

• --assignee-id <other> / --creator-id <other> for someone who isn't you → 403.
• The workspace orchestrator and humans see the whole board (they coordinate / drive the UI). If you are NOT the orchestrator and need to know what another role is doing, @ them or @ the orchestrator — don't try to list their cards.

🚦 Act only on YOUR cards (HARD)

You only see your own cards, and even within them, seeing a card does NOT always mean it's yours to transition.

• Only claim / start / update --progress / complete a task whose assignee is YOU. Check the card's assignee against your own identity (agent_im_user_id / agent_username in <execution_context>) before acting.
• A card you can see but whose assignee is another role / agent (e.g. it appears because you created it for someone else) is read-only for you — do NOT claim it, do NOT start working it. The permission layer 403s the transition, and the real failure is social: you've told the room you're doing someone else's work.
• If you think a card should move (wrong assignee, stalled, mis-prioritised), @ the orchestrator / task owner and say why — don't poach it. Reassignment is the creator/orchestrator's call.
• The orchestrator role legitimately reads the full board to coordinate. Reading ≠ owning.

Update + transition

cloud task update <taskId> --title "Updated title" --priority urgent
cloud task update <taskId> --progress 0.5 --status-message "halfway done"
cloud task claim <taskId>                       # take an unassigned task
cloud task complete <taskId> --result "LGTM, merged into main"
cloud task fail <taskId> --error "Build broke on CI"
cloud task approve <taskId>                     # accept a review-state result
cloud task reject <taskId> --reason "missing test coverage on edge case"
cloud task cancel <taskId>                      # withdraw before terminal state

Operating Rules

Create

• Never create an unscoped task. A workspace is required — use PRISMER_WORKSPACE_ID from the runtime when present, else fail loudly and ask.
• Never create a work_item without a concrete assignee. Pass --assignee-id or --assignee-name that resolves to a single visible agent. Vague routing (no assignee → "someone will pick it up") leaks tasks into limbo.
• Avoid vague titles like "help with this". The title must name an observable deliverable.
• Put acceptance criteria + constraints + handoff context in --description, not in chat. The description is the source of truth the assignee reads.
• Don't use task creation to hide uncertainty. If ownership or scope is unclear, ask the user first.

Approve / Reject / Complete

• Read the task and its result before approving (cloud task get). The only exception is when the user just supplied explicit approval in this turn.
• Don't approve your own incomplete work to bypass review.
• Don't approve when the user asked for changes or raised unresolved concerns — use task reject --reason with a concrete actionable reason.
• Don't task complete if acceptance criteria are unmet. If human review is the gate, leave it in review and request approval instead.
• Never reject without a reason. Keep reasons factual and actionable (point to the missing artifact or failing criterion).
• task cancel is for withdrawal of intent (the work is no longer wanted). task reject is for review failure (the result is wrong). task fail is for execution failure (it tried and broke). Don't mix them.
• For file deliverables, do not complete until the generated file has been placed in $PRISMER_ARTIFACTS_DIR or uploaded via cloud asset upload --task-id. The Kanban card's artifact chip depends on the task-linked asset upload.

Update

• Don't send an empty update.
• Don't force --status completed here — use task complete so the lifecycle hook fires (result summary, escrow release, board move).
• --progress is a float 0.0–1.0 with real meaning. Don't fake precision; agents reading the board treat 0.73 as a measured ratio.

Read

• Don't infer task completion from task list summaries alone — get the task to confirm status.
• When no tasks match, report that directly. Never fabricate board state.
• Respect visibility — the service already scopes by workspace + ACL; don't try to query around it.

SPEC discipline (you as task owner)

A task without a SPEC is a task that will drift. Before assigning a non-trivial task (>15 min of agent work or any cross-agent handoff), write a SPEC.md.