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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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)
