taskwarrior

---

name: taskwarrior description: Use this skill for Taskwarrior (task CLI) workflows: creating, querying, reranking, triaging, housekeeping, and completing tasks for the user's life and projects. Trigger whenever the user mentions Taskwarrior or task, recurring tasks, task triage, housekeeping, reranking, or asks to update life/project tasks in this environment; do not use for ordinary software-development "tasks" unless the local Taskwarrior system is implied.

Taskwarrior

Use this workflow when working with the user's local Taskwarrior data. Taskwarrior tracks tasks across their life and projects, so safety and exact identity matter more than speed.

The core discipline is discover before mutate: read the current state, classify what you find, propose exact changes, then execute the smallest safe command.

Operating Workflow

Use this loop unless the user asks for one narrow command:

1. Scope — name the project, area of life, date range, context, or report being worked. Done when you can state in one sentence what subset of the task system this request touches.
2. Read — use read-only commands to collect candidates and current state. Done when you have UUIDs and current field values for every task the request could affect.
3. Classify — separate capture, actionable next actions, waiting/deferred work, recurring templates, and stale/housekeeping items. Done when every candidate is assigned to one category.
4. Propose — show exact target identities and proposed changes before broad or ambiguous writes. Done when the user can see exactly what will change and on which tasks.
5. Mutate — run the smallest safe commands, targeting UUIDs. Done when each command has exited and you have captured its output.
6. Verify — re-read narrowly and report undo commands. Done when the post-write state matches the proposal and the user knows how to undo.

For triage or reranking, produce a compact table before writing:

| uuid | task | current state | proposed change | rationale | confidence |

Taskwarrior urgency is derived, not editable. Rerank by changing explicit fields: priority, due, wait, scheduled, project, tags such as +next, or dependencies.

Identity

Taskwarrior UUIDs are stable. Numeric task IDs are temporary UI handles that can change between reads.

For any mutation, target the UUID, not the numeric ID — unless the user just supplied or confirmed a displayed numeric ID.

task <uuid> modify project:Work +next    # safe
task 12 modify project:Work +next        # risky unless 12 was just displayed

When explaining a mutation plan, say plainly: numeric IDs are temporary; use UUIDs for mutations.

Creating Tasks

Create tasks with enough structure to make later querying useful, but do not invent metadata. A good task has a clear verb, optional project, optional due/wait date, and only high-signal tags.

Use -- before a literal description that could be parsed as attributes:

task add project:Finance +admin due:friday -- "Pay credit card"
task add project:Work +next wait:tomorrow -- "Draft launch checklist"
task add -- "project:Home needs scheduling"

Use task log to record already-completed work as a completed task:

task log project:Work -- "Submitted monthly report"

Ask one short question before adding when the answer materially changes the durable task shape:

• Is this a one-off task or recurring obligation?
• What is the first due date or review date?
• Which project/area owns it?
• Should it be hidden until a lead time (wait:)?

Recurring Tasks

Use recurring tasks for durable obligations, not vague intentions. Before creating one, establish:

• First due date or anchor date.
• Cadence.
• Whether it should end (until:).
• Whether it should stay hidden until a lead time (wait:).
• Whether month-end or leap-day behavior matters.

Safe creation pattern:

task add "Pay rent" due:1st recur:monthly
task add "Take out trash" due:fri recur:weekly
task add "Water plants" due:saturday wait:thursday recur:weekly
task add "Submit expense report" due:eom recur:monthly until:2026-12-31

Rules:

• recur: requires due:. Do not create task add "Thing" recur:daily.
• due: + recur: creates a hidden recurring template; visible work appears as child instances.
• Completing an instance updates the template state; future instances are generated by recurrence processing.
• Use until: to stop future generation after a cutoff.
• Use wait: for lead time; recurring children preserve the wait-minus-due offset.
• Avoid scheduled: on recurring tasks. Taskwarrior 3.4.2 copies it as an absolute value rather than recalculating it relative to each due date. Include this caveat in recurring-task answers even when the proposed commands do not use scheduled:.
• Warn on monthly tasks anchored on the 29th, 30th, or 31st; calendar-month stepping can clamp invalid dates and drift.
• Never edit internal recurrence fields such as mask, parent, or imask.
• Prefer readable recurrence values: daily, weekdays, weekly, biweekly, monthly, quarterly, semiannual, annual, or explicit forms like 2w, 2mo, 2y. Do not use bare integers like recur:2.

Inspect recurring templates intentionally:

task recurring
task all +TEMPLATE
task all +INSTANCE

For recurring series edits, target the template intentionally. Ask before changing or deleting a series.

task <template-uuid> modify project:Finance
task <template-uuid> modify until:2026-12-31
task <template-uuid> delete

Reads

Prefer machine-readable export for analysis and information for detail on a single task:

task rc.color=off <narrow-filter> export
task rc.color=off <uuid> information
task rc.color=off _projects
task rc.color=off _tags
task rc.color=off _unique project
task rc.color=off summary

Use the narrowest useful date range, project, tag, status, or UUID. Avoid dumping all tasks unless the user asks for a broad review.

Current Taskwarrior context can filter results and affect add or log. If results look surprisingly empty, inspect context before concluding there are no tasks:

task context

Mutations

For modify, annotate, append, prepend, start, stop, and done, use a UUID and verify after the command.

task <uuid> annotate "Waiting for Alex reply"
task <uuid> done
task <uuid> start
task <uuid> stop

task start and task stop mark active work; there is no time-tracking integration.

Require explicit confirmation before:

• Mutating more than one task.
• Mutating by broad filter, for example project:Work modify ....
• Marking ambiguous candidates done.
• Changing contexts or Taskwarrior config.
• Running task import, because matching UUIDs can update existing tasks.
• Running task delete.
• Running task purge.

Treat task purge as break-glass only. It permanently removes already-deleted tasks, is local-only, and is not a normal cleanup command.

Query, Triage, And Rerank

Use queries to discover the system before changing it:

task rc.color=off ready
task rc.color=off next
task rc.color=off waiting
task rc.color=off overdue
task rc.color=off status:pending project.none: export
task rc.color=off status:pending due.none: export
task rc.color=off status:pending +next export

For triage, classify each task as:

• Do now or next — clear action, available, worth surfacing.
• Schedule/defer — real task, not actionable until a date.
• Waiting — blocked by someone/something else.
• Someday/maybe — keep but hide from near-term action.
• Clarify — description is not actionable yet.
• Delete/done — no longer relevant or already completed.

For reranking, propose exact field changes rather than vague priority advice:

task <uuid> modify priority:H +next due:friday
task <uuid> modify wait:monday -next
task <uuid> modify project:Finance +admin
task <uuid> modify depends:<blocking-uuid>

Use priority sparingly. Prefer due, wait, +next, and dependencies when those better express reality.

Housekeeping

Housekeeping is a review workflow, not a blind cleanup. Start read-only, group candidates, then ask before broad changes.

Useful inspections:

task rc.color=off overdue
task rc.color=off waiting
task rc.color=off blocked
task rc.color=off blocking
task rc.color=off recurring
task rc.color=off completed end.after:today-30d
task rc.color=off status:deleted export

Good housekeeping outputs:

• Stale waiting items and proposed follow-up dates.
• Overdue items to reschedule, do, or delete.
• Pending tasks with no project or vague descriptions.
• Duplicate-looking captures.
• Recurring templates that need until: or cadence correction.

Do not purge as housekeeping. Only propose purge when the user explicitly asks for permanent deletion and understands that it is local-only and irreversible in normal workflows.

Sync

The user's Taskwarrior replicas sync against a TaskChampion sync server. After writes that the user wants visible on other devices, run task sync to push changes. Sync conflicts are resolved by TaskChampion's operational transformation; the agent does not need to resolve them manually.

After Writes

After a write, verify with a narrow read:

task rc.color=off <uuid> information

Report the result and include: Undo with task undo if this was wrong. Do not run undo twice without checking, because undo is itself not reversible.

Response Pattern

For read-only requests, answer with:

• Scope inspected.
• Key results.
• Caveats such as active context or ambiguous dates.
• Suggested next action only if useful.

For writes, answer with:

• Exact target identity (UUID).
• Exact command run, or exact command proposed if confirmation is required.
• Verification result.
• Undo command.

Ask Before Proceeding When

• The request could match multiple tasks.
• A broad filter would mutate multiple tasks.
• The current Taskwarrior context may hide relevant tasks.
• The user gave vague dates like "last Monday morning" and a precise timestamp matters.
• The command is destructive, permanent, or hard to unwind.