| name | work-track |
| metadata | {"version":"0.24.6"} |
| description | Track work items — use when creating, updating, closing, or listing work items, or when discovering unplanned work mid-flight ("we also need to…", a bug found while doing something else). |
Work tracking
Every request that produces work gets worklog items FIRST — add them before
starting, move them in_progress → done as the work happens (the
UserPromptSubmit and Stop hooks enforce this). Unrecorded work is invisible work.
All state changes go through bin/worklog. Never edit .work/*.jsonl by
hand or with shell redirects (invariant 15.4) — the CLI's append() is the
only writer.
Add an item
bin/worklog add "<title>" --body "<readable description>" \
[--level epic|story|task|subtask] \
[--kind feature|bug|ops|triage] [--milestone v0.6.0] \
[--priority P0-P3] [--parent <ulid>] [--labels a,b]
Every item gets a --body (spec §13.4). One to three sentences a junior
dev or a PM can read in the ticket: what the work is and why it matters. No
ULIDs, no repo jargon in the reading path — the sync marker carries
provenance, the body carries meaning. A ticket whose body is only a worklog
id is a policy violation. Fix gaps with worklog update <ulid> --body "...".
Taxonomy rules (spec 5.4): epics are feature or ops only — kind is free
at story/task/subtask; bugs may float free of any epic (--parent optional).
--milestone goes on leaves (story and below); an epic's milestone derives
from its children. Unclassified work defaults to kind:triage — classify
deliberately, don't guess. --type is a deprecated alias (bug →
task/bug); prefer --level/--kind.
Unplanned discoveries
Work discovered mid-flight ("we also need to…", a bug found while doing
something else) MUST be recorded BEFORE doing the work:
bin/worklog add "<title>" --unplanned --discovered-during <current-item-ulid>
--unplanned requires --discovered-during (spec 5.4).
Update / close
bin/worklog update <ulid> [--status todo|in_progress|blocked] \
[--kind feature|bug|ops|triage] [--milestone v0.6.0] \
[--priority P0-P3] [--add-label a] [--del-label b]
bin/worklog close <ulid> --status done|cancelled [--resolution "..."]
After closing items, run the ticket-sync skill so linked tickets close
remotely too.
Inspect
bin/worklog list # open items
bin/worklog list --all # includes closed
bin/worklog show <id-prefix>
After any change
Run bin/worklog roadmap-render and commit the log and roadmap together
(.work/todo.jsonl + docs/roadmap.md) — the pre-commit hook rejects a
stale roadmap.
After merging branches
The logs union-merge without conflict, but docs/roadmap.md may conflict or
go stale (both sides regenerated it). Recovery is always the same: run
bin/worklog roadmap-render, git add -A, and finish the merge commit. The
pre-merge-commit hook blocks any merge that would land a stale roadmap.
