yman for scripts and agents: the short manual, for a reader that pays per token

Paste into the project’s CLAUDE.md

yman ls -n 10 --assignee -                        # pick: unassigned, best priority first
yman show <id> -n 3                               # read: header, body, last 3 comments
yman set <id> --status doing -a <me> -m "on it"   # claim: status, assignee, note, one commit
yman done <id> -m "what changed" && yman sync     # close, explain, publish
yman add "Title" -m "body" -a <me> --relate <id>  # follow-up, linked to its parent
`yman sync` before a status change (re-`show`; stop if taken) and after (unless `autosync: push`).
Never `edit` or `-e` (opens an editor); change a body with `yman set <id> --body "..."`.
`rm` and `tags rm` need `-f` off a terminal, or refuse: `refusing to remove without -f`.
Task list asked for: `yman ls -l -n 20`, render as a table (P ID Status Title Tags),
`show <id> -n 0` the best 1-3 (it has the assignee; `ls` does not), recommend one.

Reading

ls prints one row per task, header only on a terminal; -l adds the bodies:

P  ID  STATUS  TITLE  TAGS  F  C

P is priority 0 (highest) to 9, F attachments, C comments; zero is blank and trailing empty columns are dropped. Filters AND together, -t and -q comparing lowercase: -s <status> -t <tag> --assignee <who|-> -p <0-9> --related <id> -q <text>; -n <N> caps rows after sorting; closed tasks need -a or -s <closed status>.

show <id> prints a header (related by: = tasks relating to it), the body, then attachments: and discussion:; empty sections omitted, -n <N> keeps the last N. tags lists every tag in use with its task count, closed tasks included. ls, plan, show, status, tags take --json: empty is []/null; ls/plan add body with -l.

Writing

start, done, cancel, reopen, move <id>... <status> and prio <id>... <0-9> take several ids, one commit each, and -m <text> to comment in the same commit. set <id> changes any field: --status --priority --title -a/--assignee --no-assignee --tag/--untag --link/--unlink --relate/--unrelate --body <text> --body-file <path|-> -m <text>. Every mutation is its own commit; nothing to save. comment <id> -m <text> adds a note; without -m it reads stdin to EOF, so pass -m.

Plans

An epic is an ordinary task (tag epic); its steps are add ... --relate <epic>, or all at once add --sections <file|-> --relate <epic>: one per # Title, body below. plan <epic> prints it, a count per status and the open steps sorted like ls (-a all, -n 3 what is next, -l, --json); that picks the next step, no show needed. Order with priority. A step that waits gets --waits-on <blocker> on add or set: relate plus status blocked (needs it in statuses.list); plan shows waits on <ids>. Closing the last blocker prints note: <id> no longer waits on anything open: yman move <id> todo on stderr; run it. Close the epic last, when plan lists none (closing it earlier warns with the open ids).

Streams and exit codes

stdout carries data only. Errors (error: ...), warnings and notes go to stderr.

0  ok
1  error, stderr says what
2  usage error, from the argument parser
3  a sync merge is unresolved
4  no task has that id

On 3: yman status names the unmerged files under .yman/; remove the markers (delete a folder a duplicate task id names; yman git add the side to keep of a file with no markers), then yman sync --continue or --abort; mutating exits 3 till then.

Cost and attribution

Plain output is cheapest; keep --json for jq. Cap with -n (show <id> -n 0 drops the discussion); one verb with -m beats a verb then comment. YMAN_ACTOR=<name> names you on comments and attachments; the git committer is unchanged.