How do I install the Work Track skill?

Run npx skillmds@latest add spillwavesolutions/work-track in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Work Track safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Work Track?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Work Track free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Work Track?

spillwavesolutions (@spillwavesolutions) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Work Track by spillwavesolutions — Agent Skill

Name: Work Track
Author: spillwavesolutions

File contents

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.

---name: work-trackdescription: 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 trackingEvery request that produces work gets worklog items FIRST — add them beforestarting, move them `in_progress` → `done` as the work happens (theUserPromptSubmit and Stop hooks enforce this). Unrecorded work is invisible work.All state changes go through `bin/worklog`. Never edit `.work/*.jsonl` byhand or with shell redirects (invariant 15.4) — the CLI's `append()` is theonly 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 juniordev or a PM can read in the ticket: what the work is and why it matters. NoULIDs, no repo jargon in the reading path — the sync marker carriesprovenance, the body carries meaning. A ticket whose body is only a worklogid is a policy violation. Fix gaps with `worklog update <ulid> --body "..."`.Taxonomy rules (spec 5.4): epics are `feature` or `ops` only — kind is freeat story/task/subtask; bugs may float free of any epic (`--parent` optional).`--milestone` goes on leaves (story and below); an epic's milestone derivesfrom its children. Unclassified work defaults to `kind:triage` — classifydeliberately, don't guess. `--type` is a deprecated alias (`bug` →`task`/`bug`); prefer `--level`/`--kind`.## Unplanned discoveriesWork discovered mid-flight ("we also need to…", a bug found while doingsomething 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 closeremotely too.## Inspect bin/worklog list # open items bin/worklog list --all # includes closed bin/worklog show <id-prefix>## After any changeRun `bin/worklog roadmap-render` and commit the log and roadmap together(`.work/todo.jsonl` + `docs/roadmap.md`) — the pre-commit hook rejects astale roadmap.## After merging branchesThe logs union-merge without conflict, but `docs/roadmap.md` may conflict orgo stale (both sides regenerated it). Recovery is always the same: run`bin/worklog roadmap-render`, `git add -A`, and finish the merge commit. Thepre-merge-commit hook blocks any merge that would land a stale roadmap.

Frequently asked questions

Work Track