1# yatd, _yet another td_
2
3There are many tds. This one is mine. It's in Rust, very fast, very
4small, fairly simple, and includes a skill. I intend it to be the bare
5minimum for something like a repo-specific issue tracker and possibly
6complementary to tools like [OpenSpec].
7
8[OpenSpec]: https://github.com/Fission-AI/OpenSpec
9
10Install with `mise use -g cargo:https://git.secluded.site/yatd@latest`
11or `cargo install --git https://git.secluded.site/yatd` or by cloning
12and running `make install`. Tell your agent how/when to use td by first
13installing the skill with `td skill`, then somehow referring to td when
14telling the agent to do something involving td. It shouldn't invoke the
15skill unless you mention td, allowing your agent to use other todo/issue
16tools in other repos even with this global skill.
17
18Inspired by [alosec/td].
19
20[alosec/td]: https://github.com/alosec/td/
21
22## Usage
23
24There are many ways to use something like this and I won't say any one
25is better than another. However, I tend to use it in a particular way
26and that may lead its design to faciliate that way particularly well.
27
28<details><summary>td on its own (click to expand)</summary>
29
30I first think of a feature, then tell the agent about it and ask it to
31interview me about any gaps. We go back and forth, me nitpicking things
32about what it said, it nitpicking things about what I said, until it
33feels right. Then I say something like "let's think about how we can
34break this up into the smallest units of work and create tasks with
35appropriate dependency relationships to communicate the order in which
36we must tackle them." It creates a bunch of tasks, links them, and
37probably describes what it did. I run td next to see what's bubbled up
38to the top, read through it, and decide whether it needs more work or is
39good to go as-is. If it needs more work, I start a new session with
40"let's think about {id} and plan it out some more, then log those
41decisions to the task". If it's ready, the new session begins with
42"let's get started on {id} by having a look around at the relevant code
43then breaking it down into smaller child tasks". Then depending on the
44context window and task scale, I either have it get started in this same
45session or a new one.
46
47I said it's complementary to things like OpenSpec at the beginning, but
48realise my workflow almost entirely obviates OpenSpec 🥴 I do intend to
49use them together soon and will describe whatever workflow I end up with
50then.
51
52</details>
53
54```
55$ td --help
56Todo tracker for AI agents
57
58Usage: td [OPTIONS] <COMMAND>
59
60Commands:
61 init Initialize a central project and bind the current directory to it
62 use Bind the current directory to an existing project
63 projects List all known projects in central storage
64 create Create a new task [aliases: add]
65 list List tasks [aliases: ls]
66 show Show task details
67 log Append a work log entry to a task
68 update Update a task
69 done Mark task(s) as closed [aliases: close]
70 rm Delete task(s)
71 reopen Reopen task(s)
72 dep Manage dependencies / blockers
73 label Manage labels
74 search Search tasks by title or description
75 ready Show tasks with no open blockers
76 next Recommend next task(s) to work on
77 stats Show task statistics (always JSON)
78 tidy Compact accumulated delta files into the base snapshot
79 export Export tasks to JSONL (one JSON object per line)
80 import Import tasks from a JSONL file
81 sync Sync project state with a peer via magic wormhole
82 skill Install the agent skill file (SKILL.md)
83 help Print this message or the help of the given subcommand(s)
84
85Options:
86 -j, --json Output JSON
87 --project <PROJECT> Select a project explicitly (overrides cwd binding)
88 -h, --help Print help
89 -V, --version Print version
90```
91
92## Syncing
93
94Everything is [CRDTs], so syncing is (or at least should™ be) easy! The
95built-in method uses a [Rust port][magic-wormhole.rs] of
96[magic-wormhole].
97
98- Initiate a sync on one device with `td sync`
99 - Outputs a code like `9-lurid-gecko`
100- Accept on another device with `td sync 9-lurid-gecko`
101
102[CRDTs]: https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type
103[magic-wormhole.rs]: https://github.com/magic-wormhole/magic-wormhole.rs
104[magic-wormhole]: https://magic-wormhole.readthedocs.io/en/latest/welcome.html
105
106If you want to use something like Syncthing or Nextcloud or Google Drive
107or whatever, you _should_ just be able to point the sync daemon at
108`$XDG_DATA_HOME/td/projects/`, but I've not tested this.
109
110## Bootstrapping
111
112When syncing a project to another machine, do **not** run `td init` on
113the other machine. Initialize just once on the first machine, then
114bootstrap others with `td sync` ([sync docs](#syncing)). The first
115machine will notice the other has nothing and provide everything.
116
117Running `td init` on both machines generates different `project_id`
118values and prevents sync from merging them.
119
120## Contributions
121
122I'm trying [the Jujutsu VCS] out for this project. I'm enjoying it and
123LLMs seem to do pretty well with it too. The collaboration story is a
124bit less convenient, especially since I'm also trying [pr.pico.sh]. It
125works _very_ well with git projects, but jujutsu is missing some things
126git has which [pr.pico.sh] relies on. When cloning this repo, do so with
127`jj git clone --colocate git@git.secluded.site:yatd.git` and the
128relevant git commands should work fine.
129
130[the Jujutsu VCS]: https://www.jj-vcs.dev/latest/
131
132Patch requests are in [amolith/llm-projects] on [pr.pico.sh]. You don't
133need a new account to contribute, you don't need to fork this repo, you
134don't need to fiddle with `git send-email`, you don't need to faff with
135your email client to get `git request-pull` working...
136
137You just need:
138
139- Git
140- SSH
141- An SSH key
142
143If you're using LLM agents, you might instead want to give them [my pr.pico.sh
144skill].
145
146```sh
147# Clone this repo
148jj git clone --colocate git@git.secluded.site:yatd.git
149
150# Create a new change and describe what it does
151jj new -m "Add fancy new thing" # Imperative, kernel-style commits, not Conventional Commits
152
153# When ready, create a new patch request
154git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
155
156# After potential feedback, revise and submit a new patchset
157jj amend
158git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
159
160# List patch requests
161ssh pr.pico.sh pr ls amolith/llm-projects --mine
162```
163
164See "How do Patch Requests work?" on [pr.pico.sh]'s home page for a more
165complete example workflow.
166
167[amolith/llm-projects]: https://pr.pico.sh/r/amolith/llm-projects
168[pr.pico.sh]: https://pr.pico.sh
169[my pr.pico.sh skill]: https://git.secluded.site/agent-skills#:~:text=collaborating%2Dthrough%2Dpr%2Dpico%2Dsh