diff --git a/README.md b/README.md index 9e6aa6994eb1da3d3f1c5607bcc6d4e6f5973224..bf5542acc331c2853d20a2aa03b2bd68bd02c02a 100644 --- a/README.md +++ b/README.md @@ -13,30 +13,30 @@ Install with `mise use -g cargo:https://git.secluded.site/yatd@latest` or skill with `td skill`, then somehow referring to td when telling the agent to do something involving td. It shouldn't invoke the skill unless you mention td, allowing your agent to use other todo/issue tools in other repos even with this -global skill. Td IDs are prefixed with `td-`, so pasting the ID should be -enough of a mention. +global skill. + +Inspired by [alosec/td]. + +[alosec/td]: https://github.com/alosec/td/ ## Sync Bootstrapping -When bringing a project to a second machine, do **not** run `td init` again. -Initialize once on the first machine, then bootstrap the second machine by -running `td sync` and entering the wormhole code from the first machine. +When syncing a project to another machine, do **not** run `td init` on +the other machine. Initialize just once on the first machine, then +bootstrap others by running `td sync` on the first machine, then `td +sync wormhole-code` on another. ```sh -# Machine A (already initialized project) +# Machine A (already initialized) td sync # Machine B (same repo checkout, no td project yet) -td sync +td sync 5-lurid-gecko ``` Running `td init` on both machines creates different `project_id` values and prevents sync from merging them. -Inspired by [alosec/td]. - -[alosec/td]: https://github.com/alosec/td/ - ``` $ td --help Todo tracker for AI agents @@ -44,31 +44,35 @@ Todo tracker for AI agents Usage: td [OPTIONS] Commands: - init Initialize .td directory - create Create a new task [aliases: add] - list List tasks [aliases: ls] - show Show task details - log Append a work log entry to a task - update Update a task - done Mark task(s) as closed [aliases: close] - rm Delete task(s) - reopen Reopen task(s) - dep Manage dependencies / blockers - label Manage labels - search Search tasks by title or description - ready Show tasks with no open blockers - next Recommend next task(s) to work on - stats Show task statistics (always JSON) - compact Vacuum the database - export Export tasks to JSONL (one JSON object per line) - import Import tasks from a JSONL file - skill Install the agent skill file (SKILL.md) - help Print this message or the help of the given subcommand(s) + init Initialize a central project and bind the current directory to it + use Bind the current directory to an existing project + projects List all known projects in central storage + create Create a new task [aliases: add] + list List tasks [aliases: ls] + show Show task details + log Append a work log entry to a task + update Update a task + done Mark task(s) as closed [aliases: close] + rm Delete task(s) + reopen Reopen task(s) + dep Manage dependencies / blockers + label Manage labels + search Search tasks by title or description + ready Show tasks with no open blockers + next Recommend next task(s) to work on + stats Show task statistics (always JSON) + compact Vacuum the database + export Export tasks to JSONL (one JSON object per line) + import Import tasks from a JSONL file + sync Sync project state with a peer via magic wormhole + skill Install the agent skill file (SKILL.md) + help Print this message or the help of the given subcommand(s) Options: - -j, --json Output JSON - -h, --help Print help - -V, --version Print version + -j, --json Output JSON + --project Select a project explicitly (overrides cwd binding) + -h, --help Print help + -V, --version Print version ``` ## Contributions diff --git a/SKILL.md b/SKILL.md index 67a0ce44e6e7d0c4448e1aa24ab590d2dfa93875..31ef3de12d54c7e0785a5fb7987e78449b615a07 100644 --- a/SKILL.md +++ b/SKILL.md @@ -3,20 +3,21 @@ 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 `'EOF'` HEREDOCs; they disable shell -interpolation, preventing it from messing up Markdown in the description. +Don't forget the single quotes around `'EOF'` HEREDOCs; they disable +shell interpolation, preventing it from messing up Markdown in the +description. ## Projects and initialisation -Storage is central (`~/.local/share/td/`), not per-directory. Each project -is a named Loro CRDT document. Directories are bound to projects via -`td init` or `td use`; the binding is resolved by longest-prefix match on -the canonical path. You can also override with `--project ` or the -`TD_PROJECT` env var. +Storage is central (`~/.local/share/td/`), not per-directory. Each +project is a named Loro CRDT document. Directories are bound to projects +via `td init` or `td use`; the binding is resolved by longest-prefix +match on the canonical path. You can also override with `--project +` or the `TD_PROJECT` env var. -For multi-machine setup, initialize only once. On the second machine, bootstrap -from the first with `td sync` instead of `td init` so both sides share the same -project identity. +For multi-machine setup, initialize only once. On others, bootstrap from +the first with `td sync` instead of `td init` so both sides share the +same project identity. ```bash td init myproject # create project + bind cwd to it @@ -30,13 +31,13 @@ TD_PROJECT=other td list # env override ## 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. +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. Task IDs are 26-character ULIDs. Most commands accept a unique prefix as -shorthand (e.g. the first 7 characters shown in table output). If the prefix -is ambiguous, td will tell you. +shorthand (e.g. the first 7 characters shown in table output). If the +prefix is ambiguous, td will tell you. Deletion is a soft delete (sets `deleted_at` and marks the task closed). Deleted tasks are hidden from `list`/`ready`/`next` but still visible to @@ -68,9 +69,10 @@ Flags: - -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. +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 td create "Panic in token_refresh when OAuth provider returns HTTP 429" \ @@ -118,7 +120,16 @@ td create "Child task" --parent td-a1b2c3 # for splitting tasks into smaller chu ## 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. +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 @@ -139,9 +150,26 @@ 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. - -The `log`s are your scratchpad from which another agent or human might pick up after you. Any time you discover something, like maybe the code doesn't actually line up with the spec or some constraint forces you to implement something differently from initially described or whatever else, this is where you note it down. As you're discussing things with the user, they'll communicate preferences or make decisions or tell you to do things a certain way. Any time the task doesn't already reflect those, this is where you record them. Do not EVER let these signals go unrecorded. In case there's a network outage or a power failure or any other kind of weird issue, the user needs to be able to hand this ticket in whatever form YOU left it to what will effectively be an amensic agent. It'll be competent, but like a completely fresh consultant, need lots and lots of context to get up to speed. The ticket and the logs you attach to it _massively_ help anyone coming after you. While the "what" is definitely important, be sure not to skimp on the much more important "why", such as "User said ..." or "Discovered that [code symbol] actually ...". +These, and `show` of course, but that one's self-explanatory, are your +most-run `td` commands. + +The `log`s are your scratchpad from which another agent or human might +pick up after you. Any time you discover something, like maybe the code +doesn't actually line up with the spec or some constraint forces you to +implement something differently from initially described or whatever +else, this is where you note it down. As you're discussing things with +the user, they'll communicate preferences or make decisions or tell you +to do things a certain way. Any time the task doesn't already reflect +those, this is where you record them. Do not EVER let these signals go +unrecorded. In case there's a network outage or a power failure or any +other kind of weird issue, the user needs to be able to hand this ticket +in whatever form YOU left it to what will effectively be an amensic +agent. It'll be competent, but like a completely fresh consultant, need +lots and lots of context to get up to speed. The ticket and the logs you +attach to it _massively_ help anyone coming after you. While the "what" +is definitely important, be sure not to skimp on the much more important +"why", such as "User said ..." or "Discovered that [code symbol] +actually ...". ```bash td log td-a1b2c3 "User asked for logs in show/export/import but not in list --json. Kept list untouched to avoid breaking existing scripts that parse its output." @@ -154,7 +182,16 @@ td log td-a1b2c3 "CI failed only on migration version assertions after adding 00 td log td-a1b2c3 "Ran manual round-trip (init -> create -> log -> show -> export/import -> show) to prove logs survive transfer and stay in chronological order." ``` -The `next` command traverses the graph using an algorithm that weighs tasks such that the top-scoring task is likely the one you want to start with. The algorithm accounts for unblocking other tasks, priority, and effort signals. It defaults to sorting by tasks which make the impact. Effort mode still accounts for all the signals, buts weighs them such that tasks with lower effort values bubble to the top. Only use effort mode if explicitly requested. Passing the verbose flag will show the equation resulting in the score, if the user is curious why things are sorted as they are. Only use the verbose flag if the user is curious about sorting/scoring. +The `next` command traverses the graph using an algorithm that weighs +tasks such that the top-scoring task is likely the one you want to start +with. The algorithm accounts for unblocking other tasks, priority, and +effort signals. It defaults to sorting by tasks which make the impact. +Effort mode still accounts for all the signals, buts weighs them such +that tasks with lower effort values bubble to the top. Only use effort +mode if explicitly requested. Passing the verbose flag will show the +equation resulting in the score, if the user is curious why things are +sorted as they are. Only use the verbose flag if the user is curious +about sorting/scoring. ```bash # What should I work on next? @@ -165,4 +202,5 @@ td next -n 3 # limit to top 3 td next --mode effort -v # combine flags ``` -Reminder: update the status to "in*progress" \_before* starting and _frequently_ attach high-signal, low-noise logs to the task at hand. +Reminder: update the status to "in_progress" before starting and +_frequently_ attach high-signal, low-noise logs to the task at hand.