laurigates /taskwarrior:task-release
Release an active claim without closing the task. Pairs with /taskwarrior:task-claim: claim picks the task up, release puts it back down.
When to Use This Skill
| Use this skill when... | Use a sibling skill instead when... |
|---|---|
| Pausing a task mid-flight (lunch break, context switch, end of session) | The work has landed in a commit — use /taskwarrior:task-done |
| Handing off to another agent — leaving an annotation describing where you stopped | Starting work on a fresh task — use /taskwarrior:task-claim |
| Aborting a started task because scope was wrong | Filing a brand-new task to capture the work — use /taskwarrior:task-add |
Context
- Task CLI available: !
task --version - Git repo detected: !
find . -maxdepth 1 -name '.git' -print -quit
Git probes (git rev-parse --show-toplevel, git branch --show-current)
write to stderr in a no-git cwd, and stderr from a Context backtick
aborts the skill before its body runs. Git toplevel and current-branch
resolution are done in the body via the Bash tool (where 2>/dev/null
and exit-code handling are tolerated).
Parameters
Parse $ARGUMENTS:
$0— task ID (required).- Remaining positional words — concatenate as the freeform state message for the handoff annotation. If empty, prompt for one before annotating (an empty handoff annotation defeats the purpose).
--clear-identity— clearagent/host/branch/worktreeUDAs in addition topid. Use when the next agent should not inherit any context (e.g. cross-host handoff). Default behaviour preserves these so the queue still shows who last touched the task.--no-coworker-marker— skip the/git:coworker-check --releasestep. By default, releasing the task also drops the git-side session marker so destructive ops in this clone are no longer guarded.
Execution
Execute this release workflow:
Step 1: Load the task
task "$TASKID" export | jq '.[0] | {id, uuid, description, status, start, agent, pid, host, branch, worktree, annotations}'
Use export | jq — never info / list. Capture the uuid field as
$TASK_UUID — every mutating call from Step 3 onward addresses the task by
$TASK_UUID, never $TASKID. Step 2's AskUserQuestion pause is a real gap
during which another agent's concurrent task done can renumber $TASKID
(see .claude/rules/task-id-stability.md). Decide:
| Condition | Action |
|---|---|
status is not pending |
Abort. Released tasks must be pending; if it is already closed, the release is a no-op. |
start is unset (not +ACTIVE) |
Warn but proceed — annotation + UDA drain still useful as a "I looked at this" signal. |
start is set |
Standard path. Continue. |
Step 2: Resolve state message
If the user did not pass a message, ask them for one with a single AskUserQuestion. The annotation is the handoff payload — without it the next agent has only timestamps. Keep the prompt focused: "Where did you stop? (one sentence)".
Step 3: Annotate the handoff
Annotate before stopping — if the stop fails (e.g. concurrent modify), the annotation is still captured:
task "$TASK_UUID" annotate "released by $AGENT — state: $MESSAGE"
$AGENT is read from the task's existing agent UDA (the claim stamped it); fall back to claude-${CLAUDE_SESSION_ID:0:8} if unset.
Step 4: Stop the active state
task "$TASK_UUID" stop
This clears the built-in start attribute and removes the +ACTIVE virtual tag. The task is back in the dispatch pool for /taskwarrior:task-coordinate.
Step 5: Drain identity UDAs
Always clear pid (the process is going away):
task "$TASK_UUID" modify pid:
When --clear-identity is passed, also clear the rest:
task "$TASK_UUID" modify agent: host: branch: worktree:
The empty-value field: syntax removes a UDA in taskwarrior. Default behaviour keeps agent / host / branch / worktree so task-status "Recently touched" can attribute the work.
Step 6: Drop the coworker-check marker
Unless --no-coworker-marker was passed:
Use SlashCommand to invoke `/git:coworker-check --release`.
Fallback if SlashCommand is unavailable:
bash "$(git rev-parse --show-toplevel)/git-plugin/skills/git-coworker-check/scripts/release-session.sh" --project-dir "$(pwd)"
Step 7: Report
Print:
- Task ID, description, current status (still pending)
- Time spent active (from
starttimestamp to now — read before stopping) - Annotation appended
- Identity drain:
pidonly / full drain - Coworker-check status: marker released / skipped
- Suggested next step:
/taskwarrior:task-coordinateto dispatch the now-unclaimed work onto the next wave/taskwarrior:task-claim <id>to re-claim later
Agentic Optimizations
| Context | Command |
|---|---|
| Read existing claim before release | task _get "$TASKID".agent (single-field, exit 0 even when unset) |
| Time-spent computation | task "$TASKID" export | jq '.[0].start' then compute against now |
| Bulk release of stale claims | Pair with task +ACTIVE start.before:now-4h export | jq '.[].id' |
| Skip empty-result failures | Always export | jq, never task active list |
Quick Reference
| Step | Command |
|---|---|
| Annotate | task UUID annotate "released by AGENT — state: MSG" |
| Stop active | task UUID stop |
| Clear pid | task UUID modify pid: |
| Full identity drain | task UUID modify agent: host: branch: worktree: pid: |
| Drop git marker | /git:coworker-check --release |
Related
/taskwarrior:task-claim— pair: pick up an unclaimed task/taskwarrior:task-done— close after landing (also auto-stops + drains identity)/taskwarrior:task-coordinate— finds the next dispatch candidate/git:coworker-check— sister marker that this skill drops on--release.claude/rules/agent-coworker-detection.md— combined-signal rationale.claude/rules/task-id-stability.md— why this skill resolves$TASK_UUIDonce and mutates by UUID