@@ -3,12 +3,47 @@ name: managing-tasks-with-td
description: Manages tasks with the td CLI. Use when tracking work items, creating todos, managing task dependencies, or when the user mentions td, tasks, or todos in a project using td. When the project obviously uses something else, or the user doesn't mention td explicitly, do not read.
---
+Don't forget the single quotes around `'DESC'` HEREDOCs; they disable shell
+interpolation, preventing it from messing up Markdown in the description.
+
+## General reference
+
+These are not your most-used commands, nor are they the most critical, but you
+still need reference for them. The sections following are more important than
+this one and thus contain more instruction.
+
+```bash
+td rm td-a1b2c3 td-d4e5f6 # delete one or many IDs
+td rm --recursive td-parent # required for deleting task trees
+td rm --force td-blocker # suppress dependent-unblocked warnings
+td list # all
+td list -s open
+td list -p high
+td list -e low
+td list -l frontend
+td label add td-a1b2c3 frontend
+td label rm td-a1b2c3 backend
+td label list td-a1b2c3
+td label list-all
+td show td-a1b2c3 # read a task, its metadata, and logs
+td ready # show open tasks with no active blockers
+td search "smtp" # substring match in title and description
+```
+
+## Creating tasks
+
+Flags:
+
+- -p priority: low, medium (default), high
+- -e effort: low, medium (default), high
+- -t type -d desc -l labels (csv)
+
+Titles and bodies should stand on their own a year from now, not requiring
+additional context to understand the nuances but including those nuances
+directly at task creation or by adding them later through logs.
+
```bash
-# New work — title should stand on its own a year from now
-# -p priority: low, medium (default), high
-# -e effort: low, medium (default), high
-# -t type -d desc -l labels (csv)
-td create "panic in token_refresh when OAuth provider returns HTTP 429" \
+td create "Panic in token_refresh when OAuth provider returns HTTP 429" \
-p high -e medium -t bug -d "$(cat <<'DESC'
Reproduction:
1. Point OAuth at a rate-limiting provider (or stub with httpbin/status/429)
@@ -48,21 +83,37 @@ Relevant: tests/db_stress.rs:88, db::open()
DESC
)"
-td create "Child task" --parent td-a1b2c3 # ID becomes <parent>.N
+td create "Child task" --parent td-a1b2c3 # for splitting tasks into smaller chunks
+```
+
+## Dependencies
+
+These are a core part of td; use them liberally, but appropriately. The `next` and `ready` commands both filter tasks with blockers so you have an easier time ordering work. Blocker relationships also make obvious opportunities for parallel work. When there are opportunities for parallelisation, and you have a subagent tool with write capabilities, and the tasks are small, ask the user whether they want you to invoke subagents for them. If the tasks aren't quite scoped well enough yet, ask whether they would like you to interview/question them regarding the gaps that need filling. DO NOT parallelise work without EXPLICIT user confirmation.
+
+```bash
+td dep add td-child td-blocker # child waits for blocker to close
+td dep rm td-child td-blocker
+td dep tree td-parent # subtask tree
+```
-# What's on the board?
-td list # all tasks
-td list -s open # by status: open, in_progress, closed
-td list -p high # high-priority only
-td list -e low # low-effort tasks
-td list -l frontend # by label
+## Updating tasks
-# Full context on a task
-td show td-a1b2c3
+_As soon as_ it's obvious you're working on a particular task, mark it `in_progress`. If that was wrong, the user will say so.
-# Append notes as you go, not just once at the end.
-# Focus on why: what the user asked for, what decision was made, and why.
-# Keep file paths as context, not the headline.
+```bash
+td update td-a1b2c3 -s in_progress
+td update td-a1b2c3 -p high -e low -t "Revised title" -d "Added context"
+td done td-a1b2c3 td-d4e5f6 # one or many
+td reopen td-a1b2c3 # only on explicit user request
+```
+
+## Logging and looking for work
+
+These, and `show` of course, but that one's self-explanatory, are your most-run `td` commands.
+