witan-task

Task Manager

Interactive entry point for the dependency-aware task tracker. Tasks live in the same graph as workflow projects and memory, so they can roll up to a project (project_slug), nest under an epic (parent), block one another (blocked_by), and reference code-graph symbols (symbol_refs).

The repo key is auto-detected from .git/config (the canonical HTTPS URI) — you rarely pass repo explicitly.

Claim before you work it

Any task you actually start gets claimed first — task_claim(slug="tk-...") before the first edit, every time. This is not limited to tasks you reached through this skill. It applies just as much to one you picked off the ready list in your session's injected context, one named in a witan project run prompt, or one a human mentioned by slug.

The claim is the only signal that anybody is on it. in_progress with a live lease is what makes task_ready hide it from the next session and what makes task_claim refuse a second holder — an unclaimed task being actively worked looks exactly like one nobody has touched. Two sessions have already written the same fix for the same task on the same day, each unaware of the other, because neither claimed it first.

So:

• Claim it when you decide to work it, not when you finish. A claim after the fact records history; it prevents nothing.
• Take the refusal seriously. {"claimed": false, "held_by": ...} means someone is on it. Pick another task — do not force past a live lease without a reason you can state.
• Pass session_id, not assignee. task_claim(slug=..., session_id=...) — your $CLAUDE_SESSION_ID on Claude Code, $PI_SESSION_ID on Pi (read your own platform's variable with echo, not a fallback chain: an agent launched from the other one can inherit its id), any stable per-run id elsewhere. It qualifies the holder as <you>#<session> so your own parallel sessions are told apart; without it they all claim under one name, the contention check cannot separate them, and the second session silently renews the first's lease and is told it claimed. A deployed witan cannot infer the id (a pod has no $CLAUDE_SESSION_ID, and MCP carries no session state), so an agent talking to it directly has to send it — the CLI's proxy does this for you, an MCP client does not. A success with "qualified": false and a "warning" is the server telling you this happened. Do not put the session id in assignee: that replaces the holder outright, so the claim records a session and no person. Reserve assignee for a genuinely different worker identity (a CI job, a named runner).
• Release what you drop. task_release(slug=...) if you claim something and then move on, so it returns to ready work instead of ageing out.
• Claim as you go, not in bulk. When handed a list, claim each task as you reach it. Claiming all of them up front holds leases on work you may never start, which is the same lie in the other direction.