Files
worklane/assets/SKILL.md
T
Ansho ReiandClaude Fable 5 c03f47c52d (f774a33) Record a campaign move in the history log, and bump to 0.30.0
assign was the only field writer without an entry: a ticket could leave one
campaign for another with nothing recording it. Kind gains Campaign, assign
gains the --actor flag the other four writers carry, and the entry is written
after the save and behind the no-change return, the rule every writer follows.

The entry records Campaign::name, the codename or failing that the title,
settled when the entry is written so a rename cannot change what an old entry
means. The uuid the field holds says nothing in a log line, and a before-uuid
the board no longer has reads _missing_, the way the Campaign field itself
renders a dangling one.

campaign is the longest mechanical label, so LABEL_WIDTH widens from 6 to 8
and every mechanical row moves two columns right, a deliberate output change
that makes this a minor alongside the new flag.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-24 15:49:50 +02:00

20 KiB
Raw Blame History

name, description
name description
worklane Manage tickets on a local worklane kanban board with the `worklane` CLI, backed by markdown files in a `.worklane/` directory. Use whenever you need to file, find, read, update, comment on or move a ticket, when asked what is on the board or what to pick up next, and when reporting work you are not going to do in the change at hand. Covers the four statuses, how a ticket is addressed, what belongs in each section, and the argument traps that silently swallow a flag.

worklane

A kanban board as files. Every ticket is one markdown file in .worklane/<status>/, named <uuid>_<slug>.md, and its history lives in .worklane/history/<uuid>/, one file per entry. The CLI is the only thing that writes there: do not hand-edit or hand-place a file, because the filename, the Status field and the directory have to agree and the commands are what keep them agreeing.

Commands walk up from the working directory to find the nearest .worklane, so run worklane inside the repo the ticket belongs to. Which directory you run it in is what decides which board the ticket lands on.

worklane with no subcommand opens an interactive board and needs a terminal. It is for a person, not for you: it takes over the screen and does not return until quit.

The flow

backlog → committed → reviewing → done

Move the ticket as you work it, not afterwards. worklane mv <id> --status committed before writing any code, and --status reviewing once it is done and the tests pass. The board is then true while the work is in progress, not only after it lands, which is the whole point of having a committed column.

Only one stage at a time is allowed, so a ticket left in backlog until the end cannot go straight to reviewing and has to be walked through committed anyway. Doing it up front is the same two commands in a more useful order. -f allows a backward or skipping move, for correcting a mistake.

A move is also refused while the ticket is blocked by one that is not done yet, see Relating tickets.

mv stamps the time as it goes: Committed On, Submitted On and Completed On, one field for the status the ticket is in now, shown by show among the rest of the metadata. Only the current one is kept, so the stamp says how long the ticket has been where it is, not how long each earlier stage took. Nothing else writes them, and moving a ticket back removes the stamp of the status it left.

Reading the board

worklane ls                      # every status, counts then tickets
worklane ls backlog              # one status
worklane ls --priority 1         # only the most urgent
worklane ls --tag bug            # only the tickets carrying that tag
worklane show 1b78a24            # one ticket, body and history

ls prints a seven-character id per ticket. That is what you address it by.

worklane ls --ids prints the same tickets as an id, a tab and a title, one per line and unstyled, with done included and the filters still applying. That is the form to parse when you want the ids themselves: worklane ls --ids | cut -f1. The decorated listing is for reading, not for cutting up.

The filters compose in any combination, with each other and with the status positional: worklane ls backlog --tag bug --priority 1. --tag takes one tag and matches it against the whole values of the comma-separated Tags field, case sensitively, so --tag bug finds neither a ticket tagged bugfix nor one tagged Bug. A ticket with no tags matches none. A tag nothing carries lists nothing rather than failing, so when a listing comes back empty check the spelling against a ticket you know is tagged.

worklane tags answers the other question, the one --tag cannot: what tags exist. One line per tag, alphabetical, as the tag, a tab and how many tickets carry it. Case sensitive, like the filter, so bug and Bug list separately and land next to each other, which is where a near-duplicate is spotted. Read it before inventing a tag, and read it when a --tag filter comes back emptier than expected.

Working a ticket

worklane mv 1b78a24 --status committed
worklane check 1b78a24 3                      # tick acceptance criterion 3
worklane check 1b78a24 "the footer describes"  # or a substring of it
worklane check 1b78a24 1 3 "the footer"        # several in one call
worklane check 1b78a24 all                     # every criterion on the ticket
worklane uncheck 1b78a24 3
worklane comment 1b78a24 "Found the cause: the offset was never passed to the widget."
worklane mv 1b78a24 --status reviewing

Criteria are numbered by show. With no criterion given, check prompts when there is a terminal and otherwise fails with the numbered list, so always pass the criteria when you are not sitting at a prompt.

One call takes as many terms as you like, mixing numbers and substrings, and all stands for every criterion on the ticket. Use it when the work is done: it is one write instead of one per box. all is a keyword, checked before the text, so a criterion whose own words include "all" is reached by its number or by a longer substring.

Every term is resolved before anything is written. One term that matches nothing, or matches more than one criterion, refuses the whole call and names that term, so the ticket is never left half-marked. A criterion already in the state you asked for is reported unchanged rather than refused, and a call that would change nothing writes nothing. Both apply to uncheck exactly as they do to check.

Filing a ticket

worklane add \
  --title "The tui detail view cannot scroll" \
  --description "Opening a ticket and pressing down moves to the next one instead." \
  --description "" \
  --description "Up and down are bound to select_card unconditionally, src/main.rs." \
  --acceptance "PageUp and PageDown scroll the detail view" \
  --acceptance "The footer describes the keys that exist" \
  --plan "Add a scroll offset to Board and pass it to Paragraph::scroll" \
  --plan "Clamp against the wrapped line count, not the raw line count" \
  --priority 2 --tags bug,tui

add always lands in backlog. Nothing is created without --title.

  • --description is the case for the ticket: the symptom, then what is actually wrong, naming the files, functions and settings involved. Repeat the flag for more lines; an empty --description "" between two values is a paragraph break.
  • --acceptance takes one criterion per flag, each a statement that can be checked off as true or false.
  • --plan takes one step per flag, numbered for you.
  • --priority runs 1 (most urgent) to 5 (least), and is left unset if omitted.
  • --due takes YYYY-MM-DD and nothing else. Anything that is not a real calendar date in that exact form, 2026-8-9 and 2026-02-30 included, is a usage error with nothing written. The same parser guards set --due.

Editing afterwards, on a ticket in any status:

worklane set 1b78a24 --priority 1               # replace a field
worklane set 1b78a24 --title "A better title"   # renames the file, keeps the uuid
worklane set 1b78a24 --clear due                # take a value away again
worklane set 1b78a24 --clear tags --clear plan   # as many fields as you like
worklane append 1b78a24 --acceptance "One more criterion"
worklane append 1b78a24 --description "What was learned since."
worklane chown alice 1b78a24                    # hand the ticket to someone
worklane chown --clear 1b78a24                  # hand it back to nobody

set replaces, append adds, --clear empties. Neither set nor append has --owner or --status: owner is chown's and status is mv's, so each field has exactly one writer. A field set to the value it already holds is reported unchanged and nothing is written, and so is a field cleared that was already unset.

--clear takes the field as its value, one of due, tags, priority, description, acceptance or plan, and repeats. It writes back exactly what add writes for a field it was never given: _Not set_, _None_ for tags, and the section placeholder. There is no --clear title, because a title addresses the ticket and names its file. There is no --clear owner either: that is chown --clear <ticket>, which takes the ticket in the flag since there is no user to give, and returns the field to unset rather than to the git user. Replacing and clearing the same field in one call is refused rather than resolved.

chown takes the user first and the ticket second, after Unix chown, which is the one command here that does not start with the ticket. The user is free text and is checked against nothing. Swap the two and the call fails, because the username has to resolve as a ticket. --clear replaces both arguments with the ticket alone.

worklane init creates .worklane/ with the four status directories and the campaigns directory beside them, for a repo that has no board yet.

Relating tickets

worklane relate 1b78a24 --blocked-by 4179958     # this one waits on that one
worklane relate 1b78a24 --regression-of 6d327df  # this one broke that one's fix
worklane relate 1b78a24 --relates-to 7bfb9fc     # neighbours, no dependency

One flag per kind, and each repeats. The ticket comes first and the flag says what it is to the target, so read the call as a sentence: relate A --blocked-by B means A waits on B. Only one side is stored, on the ticket you name, and show derives the other end for the ticket at the far side, so never record both directions.

--blocked-by is enforced: mv refuses to move a ticket while a ticket it is blocked by is not in done, whichever move it is, and names every open blocker. -f moves it anyway, beside the backward and skipping moves it already allows. The other two kinds are reference data and never refuse anything.

Recording a relation the ticket already holds reports no change. A ticket cannot relate to itself, and a target that later disappears shows as _missing_ rather than silently going away.

show marks each row twice, kind then status. The kind is × for blocked by and blocks, → for relates to, ← for regression of and regressed by; both directions of one kind carry one mark, and the label is what says which end you are on. The status is the target's own: ○ backlog, ◐ committed or reviewing, ● done, and ? for a target the board no longer holds. So blocked by × ● (1b78a24) is a blocker that is finished and blocked by × ○ (1b78a24) is one nobody has started. The board draws the same block.

Colour is what tells committed from reviewing, since both are ◐, and your output is a pipe, so you do not get the colour. Read ◐ as under way, and if it matters which stage, worklane show on that target says so in its Status field. ● and ○ are unambiguous without it, which are the two answers usually being asked for.

Campaigns

A campaign groups the tickets that have to be finished together: a release, a migration, anything whose parts are separate tickets but whose goal is one thing. It is a file of its own under .worklane/campaigns/, with a title and a description, and it sits in no status directory. Its state is derived instead, open until every member is done, so there is no such thing as a done campaign holding an open ticket.

worklane campaign add --title "First public release" --codename v1 \
  --description "Everything that has to ship before the tag."
worklane campaign ls                    # every campaign, its codename, how far it has got
worklane campaign ls --ids              # id and title, tab separated, like ls --ids
worklane campaign show v1               # its body, then its members by status
worklane campaign set v1 --title "..."  # replace the title, description or codename
worklane campaign append v1 -d "..."    # add a paragraph to the description
worklane assign v1 1b78a24              # put a ticket in it
worklane ls --campaign v1               # only that campaign's tickets

Give a campaign a --codename. One word, v1 or beaver. It is what the board draws on every card in the campaign, because a uuid does not fit there and a title is a sentence, and it is the shortest thing that addresses the campaign at the command line. Optional: a campaign without one is drawn and listed by its short id instead, which resolves but says nothing. campaign set <campaign> --codename <word> gives one to a campaign that is already filed, which is what every campaign filed before the field existed needs. Replacing a codename it already has needs --force: that word is how the campaign is referred to on the board and at the command line, so changing it is a decision rather than a correction. Setting the one it already has is a no-op either way.

campaign set and campaign append are the only ways to change a campaign after it is filed. set replaces the title, the description or the codename; append adds a paragraph to the description, which is what to use when the description is right and only incomplete, since replacing prose to add a sentence to it is how the rest of it gets lost. An empty --description "" between two values is a paragraph break, exactly as it is for a ticket, and a call whose every value is blank is refused: a campaign's description cannot be emptied. There is still no way to change a campaign's owner.

append here is campaign append and not the top-level append, which takes a ticket. The two objects are addressed the same way, so the command is what says which one is meant.

assign takes the campaign first and the ticket second, like chown, and is the only writer of the field. add has no --campaign and neither has set, so membership has one writer the way owner and status do.

A ticket is in at most one campaign, so assigning one that already belongs somewhere moves it rather than adding a second. Assigning it to the campaign it already names reports no change and writes nothing.

campaign show lists done members too, unlike ls, which leaves the done column out of its listing: a campaign is precisely the question of what is finished against what is left.

A campaign is addressed the way a ticket is, by uuid prefix, title or filename, and by its exact codename, which wins over all three. So assign v1 1b78a24 reaches the campaign codenamed v1 even if another campaign's title contains v1. It is not a ticket, though. Passing one where a ticket is expected is refused with a message saying so, and there is no way to move a campaign, because it has no status to move.

Search the backlog before filing

Run worklane ls in the directory the ticket would land in and look for the same issue, including tickets already committed, in review or done. Search by the symptom and by the name of the function or setting involved, not only by your own phrasing of the title: an existing ticket will have been written from a different angle.

  • Already there and still open: add what you learned as a comment, not a second ticket.
  • Already there and closed, but the issue is back: file a new ticket naming the old id, and record it with relate <new> --regression-of <old>. There is no way to reopen one, and moving a done ticket back would destroy the record of the original fix.
  • Related but not the same: file it, and record it with relate <new> --relates-to <old> rather than only mentioning the id in prose.

What the board records about your work

show ends with a HISTORY block: every comment on the ticket and every change to its status, owner, tags or campaign, oldest first, each naming who made it. You do not write these by hand. mv, chown, set --tags and assign record themselves, and a call that changes nothing records nothing. A campaign move is recorded by codename, or by title for a campaign that has none, not by the uuid the field holds.

HISTORY
────────────────────

status    backlog → committed  claude (2026-08-24 12:45:00)

From claude (2026-08-24 13:10:22)
  The offset was never passed to the widget.

owner     _Not set_ → Ansho Rei  claude (2026-08-24 13:11:04)

campaign  _Not set_ → v1  claude (2026-08-24 13:12:30)

Nothing else is logged: ticking a criterion, and editing the title, description, plan, priority or due date, leave no entry. When one of those matters, say so in a comment. An implementation plan rewritten because the first one was wrong is worth a sentence; the edit itself is not recorded and nobody can reconstruct why from the file.

Read the block before picking a ticket up: it says whether somebody has already had it in committed and sent it back, which the current status alone does not.

Who your entries are attributed to

Every comment carries an author, and by default that is the git user of the machine you are running on, which is the human whose checkout it is and not you. Set WORKLANE_ACTOR in your own environment and it becomes the author of every entry you write, so a board several agents write to says which of them said what:

WORKLANE_ACTOR=claude worklane comment 1b78a24 "The offset was never passed to the widget."

Set it once where your session's environment is configured, not on each call: env in ~/.claude/settings.json for Claude Code, and the environment opencode is started with for opencode, since it passes its own environment to the tools it runs. --actor overrides it for one call and is spelled the same on every command that writes an entry, comment, mv, chown, set and assign. An empty value counts as unset and falls back to the git user, and with nothing at all the author is unknown. It is free text, checked against nothing: name yourself something a person reading the board will recognise.

On chown, --actor is not the user argument: worklane chown alice 1b78a24 makes alice the ticket's owner, and --actor says who made that change.

If the variable is not set and you cannot set it, pass --actor rather than letting the comment claim to be the user's.

Shell completions

worklane completions fish > ~/.config/fish/completions/worklane.fish

For the person's shell, not for you, and bash, zsh, elvish and powershell are there too. Only fish completes ticket ids, which it does by running worklane ls --ids, so a stale binary on PATH completes nothing and the fix is to reinstall it.

Addressing a ticket

Every command that takes a ticket accepts, in this order of precedence:

  1. a UUID prefix, from four characters up
  2. a substring of the title
  3. a substring of the filename

The first tier that matches anything wins outright; the later tiers are not consulted. This matters because ticket titles quote other tickets' ids, and a flat search reported an exact id as ambiguous against whichever title mentioned it. An ambiguous match prints the candidates and exits 1 rather than guessing.

Traps

  • Prose arguments accept a leading hyphen: --title, --description, --acceptance, --plan and the comment body. A criterion reading --print is supported is stored, not parsed as a flag. The cost is that a genuinely mistyped flag there lands as content instead of failing, so read back what you wrote with worklane show.
  • --due, --priority, --tags, --owner, --actor and --status do not accept one, so a mistyped flag on those is a usage error and nothing is written.
  • A ticket argument that starts with a hyphen needs the flags first and a separator: worklane mv --status committed -- -leading-title.
  • A comment body of exactly -- needs its own separator: worklane comment 1b78a24 -- --.
  • An empty value for a scalar is a usage error, not a way to clear the field: use --clear. For a section an empty value is a paragraph break, so it cannot mean empty the section either, and an all-blank one is refused with the --clear for it named.
  • comment has no --owner. Owner is the ticket's assignee, which chown writes; the author of a comment is --actor or WORKLANE_ACTOR. The old spelling is a usage error, not an alias.
  • Piping is safe: worklane ls | head -3 exits on the closed pipe instead of panicking.