Add a taskwarrior task with blueprint linkage and optional GitHub issue. Use when adding coordination tasks, linking a blueprint WO, or mirroring a GitHub issue locally.
Add a taskwarrior task with blueprint linkage and optional GitHub issue. Use when adding coordination tasks, linking a blueprint WO, or mirroring a GitHub issue locally.
File a coordination task. When a GitHub remote is present, offer optional linkage so GitHub stays the system of record and taskwarrior stays the parallel-safe query layer.
When to Use This Skill
Use this skill when...
Use task-status / task-coordinate / task-done instead when...
Filing a brand-new coordination task with bpid: / bpdoc: linkage
Auditing existing queue health — use task-status
Mirroring a GitHub issue into the local queue via ghid:
Picking the next-N candidates for a parallel wave — use task-coordinate
Pre-filling a task body from gh issue view output
Closing an in-flight task and draining its tracker — use task-done
Git probes (git rev-parse --show-toplevel, git remote) write to stderr
in a no-git cwd, and stderr from a Context backtick aborts the skill
before its body runs. Project / remote resolution is done in the body
(Step 2 below), where 2>/dev/null and exit-code handling are available.
Parameters
Parse $ARGUMENTS:
Freeform short description (required).
Optional inline project:<name> to override the auto-detected project.
Optional --no-project to file the task without any project (cross-cutting work).
Optional native scheduling fields (prefer these over manual +blocked* bookkeeping):
due:<date> — deadline. Feeds urgency and surfaces the task as / in / .
+DUE
+OVERDUE
task-coordinate
task-status
scheduled:<date> — earliest start. The task only becomes +READY once this date passes, so future work stays out of dispatch candidates.
wait:<date> — hide the task entirely until the date. Use for "blocked on merge until X" instead of a hand-managed +blocked_on_merge tag — taskwarrior auto-unhides it.
recur:<freq> (e.g. weekly, monthly) with a due: — repeating maintenance chores. Requires due:.
until:<date> — auto-delete the task on that date. Use for short-lived trackers that should expire if not actioned.
Tag naming gotcha — hyphens silently break tags. Taskwarrior parses
- mid-token as exclude-filter syntax, even inside a +tag argument.
+blocked-on-merge is parsed as +blocked AND -on-merge, so the tag
never lands and the literal +blocked-on-merge string ends up appended
to the description as plain text (urgency does not tick up). Single-
quoting ('+blocked-on-merge') does not help — this is a taskwarrior
parser quirk, not a shell issue. Use underscores or camelCase instead:
+blocked_on_merge or +blockedOnMerge. The same applies to any tag
name containing a hyphen.
Project resolution
By default every task is filed under the current repo's project so
/taskwarrior:task-status and /taskwarrior:task-coordinate only see
tasks relevant to where the agent is working. Resolve the project in
this order:
Explicit project:<name> in $ARGUMENTS.
--no-project → file with no project (rare; cross-cutting work).
Basename of git rev-parse --show-toplevel 2>/dev/null, run via the
Bash tool (where stderr suppression and non-zero exits are tolerated).
If no git repo (Step 3 returned empty), basename of cwd.
Cross-check the resolved name against Known projects and reuse the
exact spelling when it matches (case-insensitive) — taskwarrior treats
MyRepo and myrepo as different projects.
Execution
Execute this workflow:
Step 1: Ensure UDAs exist
The canonical 10-UDA set (5 linkage: bpid / bpdoc / bpms / ghid /
ghpr; 5 identity: agent / pid / host / branch / worktree) lives in
one place — the shared ensure-udas.sh script. Check for missing UDAs:
Identity UDAs are not set by task-add itself — /taskwarrior:task-claim
stamps them when an agent picks the task up. The same script backs the
SessionStart drift-probe, so the install logic is single-sourced.
Step 2: Detect GitHub mode
GitHub mode is active when all of:
git config --get remote.origin.url is non-empty
gh auth status exits 0
If either fails, skip GitHub-related branches in later steps.
Step 3: Duplicate check by bpid
If bpid: was given, run parallel-safe and constrain to the resolved
project so a matching bpid in another repo's queue is not surfaced as
a false-positive duplicate:
Never use task bpid:"$BPID" list — it exits 1 on empty result and cancels sibling tool calls in parallel batches (see .claude/rules/parallel-safe-queries.md).
If a matching open task exists, report the ID and ask whether to update instead of re-add.
Step 4: Optionally pre-fill from a GitHub issue
When GitHub mode is active and either ghid: is set or the description looks like an issue reference:
Offer to copy title into description, map labels to tags, and capture the issue number into the ghid UDA.
If the user wants a new issue created, use:
gh issue create --title "$TITLE" --body "$BODY"
…then capture the returned issue number into ghid. Skip this branch entirely in local-only mode.
Step 5: Create the task
Compose the taskwarrior add command from the collected inputs. Always
include project: (the resolved project from Parameters) unless the
user passed --no-project. Quote every field; tags use the +tag form:
Run with only the fields that were provided; omit empty UDAs and empty date
fields entirely rather than passing uda:"" / due:"". For a recurring chore,
pass recur:weekly due:monday (recurrence requires a due:); for a
self-expiring tracker, add until:eom.
Capture the stable UUID
After task add succeeds, resolve the new task's UUID via the
+LATEST virtual tag as a separate Bash call — never chain it to
task add with &&:
Use task +LATEST uuids (or task +LATEST export | jq -r '.[0].uuid'),
nottask +LATEST _get uuid. _get is a DOM accessor that takes an
<id>.<attribute> reference (task _get 141.uuid); given a tag filter it
silently returns empty (exit 0), capturing no UUID — which silently
reverted the #1417 drift fix until corrected.
Numeric IDs shift; UUIDs do not. A numeric ID is a display index over
pending tasks — completing any other task (often in a parallel session)
shifts every higher ID down by one, so task 141 annotate ... run minutes
after the add can silently hit a different task. Capture the immutable
UUID at create time and address the task by UUID for later annotate /
modify / done. See .claude/rules/task-id-stability.md.
Sequential WOs: use depends: for ordered chains
For work orders that must land in sequence (e.g., WO-058 → 059 → 060),
set depends: on each downstream task pointing to its predecessor's
taskwarrior numeric ID. When the predecessor closes with task done,
taskwarrior automatically unblocks all dependents — no manual
intervention needed (see docs/task-tracking.md § Lifecycle):
# WO-059 waits for WO-058 (taskwarrior ID 51)
task add "WO-059: ..." bpid:WO-059 +wo project:myrepo depends:51
# WO-060 waits for both
task add "WO-060: ..." bpid:WO-060 +wo project:myrepo depends:51,52
Step 6: Report
Print:
New task ID and UUID (from Step 5; quote the UUID so future agents address the task by it, not the shift-prone numeric ID)
