A file-based task manager
Add AGENTS.md with the agent-facing tsk crib sheet
A short, operational reference for agents working in this repo: the
commands they'll actually use, the namespace/queue convention (tsk vs
claude), how to record TODOs in the claude queue without polluting the
user's stack, and the markup grammar for tsk show.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+88
+88
AGENTS.md
+88
AGENTS.md
···
1
+
# tsk for agents
2
+
3
+
`tsk` is the task tracker maintained alongside this codebase. Use it to
4
+
discover what to work on, record TODOs you spawn, and mark work done.
5
+
6
+
## Quick reference
7
+
8
+
```
9
+
tsk list # active queue, top first
10
+
tsk show -T tsk-N # render one task (rich text)
11
+
tsk show -T tsk-N -x # also dump properties as YAML front-matter
12
+
tsk push -- "title" # new task at top of active queue, status=open
13
+
tsk push -- "title
14
+
body" # multi-line title gets split at first newline
15
+
tsk push -- "title" -b - # read body from stdin
16
+
tsk drop -T tsk-N # remove from queue, flip status=done
17
+
tsk edit -T tsk-N # open $EDITOR on the task body
18
+
```
19
+
20
+
## Properties
21
+
22
+
Every task has zero or more text values per property. Status is auto-managed
23
+
(`open` on push, `done` on drop). Anything else is set by hand:
24
+
25
+
```
26
+
tsk prop add -T tsk-N <key> <value> # append a value
27
+
tsk prop set -T tsk-N <key> <values...> # replace the whole list
28
+
tsk prop unset -T tsk-N <key> [<value>] # drop one value, or the whole key
29
+
tsk prop list -T tsk-N # all (key, value) lines on a task
30
+
tsk prop find <key> [<value>] # tasks with that key (= value)
31
+
tsk prop find status open # all in-progress tasks
32
+
```
33
+
34
+
## Namespaces and queues
35
+
36
+
The repo has two of each by convention:
37
+
38
+
| Kind | `tsk` | `claude` |
39
+
|-------------|--------------------|----------------------------|
40
+
| Namespace | user-owned task ids| agent-owned task ids |
41
+
| Queue | user's backlog | agent's backlog (TODOs) |
42
+
43
+
Both are pushed/shared at `refs/tsk/{namespaces,queues,tasks,properties}/*`.
44
+
The active selection is per-clone (lives in `<git-dir>/tsk/`):
45
+
46
+
```
47
+
tsk namespace current # what you're reading/writing as
48
+
tsk queue current # what your push/list/drop affect
49
+
tsk switch <name> # switch namespace (no arg = fzf-pick)
50
+
tsk queue switch <name>
51
+
```
52
+
53
+
## When you spawn a TODO
54
+
55
+
If you find scope-creep or follow-up work, push it to the `claude` queue
56
+
rather than expanding the current task or dropping a `// TODO:` in code:
57
+
58
+
```
59
+
tsk queue switch claude
60
+
tsk push -- "<short title>
61
+
<body explaining why and what to do>"
62
+
tsk queue switch tsk # switch back when done
63
+
```
64
+
65
+
This keeps the user's `tsk` queue free of agent-internal bookkeeping while
66
+
still surfacing the work for later.
67
+
68
+
## Sync with the user
69
+
70
+
Local refs aren't visible to the user until pushed:
71
+
72
+
```
73
+
tsk git-push # push refs/tsk/* to origin (also runs after assign/reject)
74
+
tsk git-pull # fetch + force-update local refs/tsk/*
75
+
tsk inbox # auto-pulls then lists pending inbox items
76
+
```
77
+
78
+
## Conventions for agents working this repo
79
+
80
+
- Always `tsk list` first. Don't invent work; pick the top task or ask.
81
+
- Run from `./target/release/tsk` after any rebuild (the user's installed
82
+
`tsk` may lag behind your changes).
83
+
- Drop a task only when the work is committed (or the user has confirmed).
84
+
- Properties you set are pushed; treat them as user-visible state, not
85
+
scratch space.
86
+
- Markup in task bodies: `!bold!`, `*italic*`, `_under_`, `~strike~`,
87
+
`=highlight=`, `` `code` ``, `[text](url)`, `[[tsk-N]]`. Stripped on
88
+
`tsk show -R`.