task-add

What this skill does

# /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 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:

1. Explicit `project:<name>` in `$ARGUMENTS`.
2. `--no-project` → file with no project (rare; cross-cutting work).
3. Basename of `git rev-parse --show-toplevel 2>/dev/null`, run via the
   Bash tool (where stderr suppression and non-zero exits are tolerated).
4. 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

If `task _udas` output lacks any of `bpid`, `bpdoc`, `bpms`, `ghid`, `ghpr` (linkage UDAs) or `agent`, `pid`, `host`, `branch`, `worktree` (identity UDAs populated by `/taskwarrior:task-claim`), offer to install them:

```bash
# Linkage UDAs
task config uda.bpid.type string
task config uda.bpid.label "Blueprint ID"
task config uda.bpdoc.type string
task config uda.bpdoc.label "Blueprint doc"
task config uda.bpms.type string
task config uda.bpms.label "Milestone"
task config uda.ghid.type numeric
task config uda.ghid.label "GH Issue"
task config uda.ghpr.type numeric
task config uda.ghpr.label "GH PR"

# Identity UDAs (populated by task-claim, drained by task-release / task-done)
task config uda.agent.type string
task config uda.agent.label "Agent ID"
task config uda.pid.type numeric
task config uda.pid.label "Agent PID"
task config uda.host.type string
task config uda.host.label "Host"
task config uda.branch.type string
task config uda.branch.label "Git branch"
task config uda.worktree.type string
task config uda.worktree.label "Worktree path"
```

Install only with user confirmation on first run per host. Identity UDAs are not set by `task-add` itself — `/taskwarrior:task-claim` stamps them when an agent picks the task up.

### Step 2: Detect GitHub mode

GitHub mode is active when all of:

1. `git config --get remote.origin.url` is non-empty
2. `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:

```bash
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:

```bash
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:

```bash
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:

```bash
task add "$DESCRIPTION" \
  project:myrepo \
  bpid:"$BPID" \
  bpdoc:"$BPDOC" \
  bpms:"$BPMS" \
  ghid:"$GHID" \
  ghpr:"$GHPR" \
  +wo +gh
```

Run with only the fields that were provided; omit empty UDAs entirely rather than passing `uda:""`.

#### 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 `&&`:

```bash
task +LATEST _get uuid
# Created task 141.
# d14a6e5e-1c60-4cfd-9dd0-8a9fe7659b74
```

> **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 the user-global rule `taskwarrior-bulk-operations.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`):

```bash
# 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)
- 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 |