/taskwarrior:task-add
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 |
Context
- Task CLI available: !
task --version
- Git repo detected: !
find . -maxdepth 1 -name '.git' -print -quit
- GH auth: !
gh auth status
- Existing UDAs: !
task _udas
- Known projects: !
task _projects
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 inline
bpid:WO-012 / bpdoc:docs/wo/012.md / bpms:M6 / ghid:145 / ghpr:99 fields.
- Optional native scheduling fields (prefer these over manual
+blocked* bookkeeping):
due:<date> — deadline. Feeds urgency and surfaces the task as +DUE / +OVERDUE in 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.- Dates accept taskwarrior synonyms (
today, eow, eom, monday, due-4d, ISO 2026-07-01).
- Optional tags:
+wo, +prp, +fr, +re, +gh, +pr_ready, +needs_review, +blocked_on_merge, +blocked.
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:
bash "${CLAUDE_SKILL_DIR}/../../scripts/ensure-udas.sh" --check
If it reports UDAS_MISSING greater than 0, confirm with the user (declarations
persist in ~/.taskrc), then install them on first run per host:
bash "${CLAUDE_SKILL_DIR}/../../scripts/ensure-udas.sh"
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-emptygh 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:
task project:myrepo bpid:"$BPID" export | jq '.[] | {id, description, status}'
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:
gh issue view "$GHID" --json number,title,body,labels,state
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:
task add "$DESCRIPTION" \
project:myrepo \
bpid:"$BPID" \
bpdoc:"$BPDOC" \
bpms:"$BPMS" \
ghid:"$GHID" \
ghpr:"$GHPR" \
due:"$DUE" \
scheduled:"$SCHEDULED" \
wait:"$WAIT" \
+wo +gh
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 &&:
task +LATEST uuids
Use task +LATEST uuids (or task +LATEST export | jq -r '.[0].uuid'),
not task +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):
task add "WO-059: ..." bpid:WO-059 +wo project:myrepo depends:51
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)
- Project (auto-detected / overridden /
--no-project)
- bpid → bpdoc → bpms chain
- ghid/ghpr if linked
- Tags applied
- Suggested next step (
/taskwarrior:task-status, /taskwarrior:task-coordinate, or /taskwarrior:task-claim if the user is about to start)
Agentic Optimizations
| Context | Command |
|---|
| Capture stable UUID after add | task +LATEST uuids |
| Duplicate check by bpid | task bpid:WO-012 export | jq '.[] | {id, status}' |
| Pre-fill from issue | gh issue view 145 --json number,title,body,labels |
| Next ready (unblocked + scheduled-due) | task status:pending +READY export | jq '.[:3]' |
| Skip empty filter exit | Always use export | jq, never list |
Quick Reference
| Flag / field | Purpose |
|---|
project: | Project (defaults to repo basename) |
--no-project | File without a project (cross-cutting) |
bpid: | Blueprint ID link |
bpdoc: | Blueprint doc path |
bpms: | Milestone |
ghid: | GitHub issue number |
ghpr: | GitHub PR number |
due: | Deadline — feeds urgency, surfaces +DUE/+OVERDUE |
scheduled: | Earliest start — gates +READY |
wait: | Hide until date (auto-unhides) — prefer over +blocked_on_merge |
recur: | Repeat frequency (needs due:) |
until: | Auto-delete date |
+wo | Work order |
+prp | PRP |
+fr | Feature request |
+re | Research |
+gh | Linked to GitHub |
+pr_ready | Open PR waiting |
+blocked_on_merge | Waiting on another PR |
Related
/taskwarrior:task-status — see current queue/taskwarrior:task-claim — claim a task and stamp identity UDAs/taskwarrior:task-done — close an open task (fires auto-unblock for depends: chains)/taskwarrior:task-coordinate — next-agent candidates for a wave.claude/rules/parallel-safe-queries.md — why export | jq, never list.claude/rules/task-id-stability.md — why the captured UUID must be used for later annotate/modify/doneblueprint-plugin:feature-tracking — FR/WO IDs that bpid points attaskwarrior-plugin/docs/task-tracking.md — full lifecycle including depends: + auto-unblock pattern
