campaign ls printed every campaign and offered no way to narrow it, and the row was assembled by hand, so a long title pushed the standing out of line with the row above it and the created date the file already carries was not shown at all. --state takes open, done or empty and matches against Standing::state(), so the derived value keeps one definition: a campaign reads [open] in the listing if and only if --state open lists it. --state rather than --status, which names one of the five ticket statuses everywhere else and would invite --state backlog here. empty is the third value because an empty campaign derives None deliberately, and a filter that could not reach those would leave what has been filed and forgotten answerable only by reading the whole listing. A filter that matches nothing names the value back, since a silent listing reads as the other empty case. The filter reaches --ids as well, the way ls --ids keeps its own, and is the only thing that makes that path count members: an unfiltered completion is as cheap as it was. The columns are measured on the raw values and padded before anything is painted, the rule metadata_cells follows. The codename is measured with the title rather than given a column of its own: a campaign filed without one spends nothing on it, so a column for it would be one most rows pad into and some leave empty, and what a reader lines up is where a name ends and its progress begins. A flag's possible values now come off the command that holds the flag, so campaign ls --state reaches ls's own arguments rather than campaign's. The prompt offered nothing there while fish offered the three values, which made a liar of the rule that a ValueEnum added anywhere is typeable on the board the day it is added. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
27 KiB
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 five 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, with discarded off to one side
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 it would take the ticket a column ahead of one it is
blocked by: a pair can be committed together and reviewed together, and only the move to
done waits for the blocker to land. See Relating tickets.
mv stamps the time as it goes: Committed On, Submitted On, Completed On and
Discarded On, shown by show among the rest of the metadata. They accumulate, so a
ticket that walked the whole flow carries all of them side by side and the journey is
legible; presence means it got that far and has not been sent back past it, not that it
is there now, which is what Status says. Moving a ticket back drops the stamps of every
stage after where it lands.
Discarding a ticket
worklane mv <id> --status discarded is where a ticket goes that will not be done: a
duplicate, something obsolete, something that turned out to be wrong. It keeps the record
and the relations, which deleting the file by hand would destroy.
worklane mv 1b78a24 --status discarded
Reachable from any status and needs no -f, because discarding is not a stage of work: a
backlog ticket does not have to be walked through committed to be abandoned. Say why
in a comment before you discard it. The status records that it will not happen and
nothing records what was decided, and that is the question somebody asks in six months.
What it means everywhere else:
lsleaves it out of the listing and keeps it in the counts, the way it treatsdone.ls discardedand--idsstill reach it- A campaign counts a discarded member as finished: the work left the campaign rather than sitting in it unfinished
- A discarded ticket blocks nothing, so a ticket waiting on it can move anywhere
- Discarding a ticket that open tickets are blocked by is refused, naming them: their
plans depended on this work, so they need a look first.
-fsays you looked - Getting it back is a backward move, so it needs
-f:worklane mv 1b78a24 --status backlog -f
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 and discarded 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.
Say why on the unusual moves: worklane mv 1b78a24 --status backlog -f --reason "the first plan was wrong". The reason is recorded inside the history entry beside the
transition it explains and rendered indented under its row, in show and on the board.
Optional on every move; a refused or no-op move records nothing even with one.
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.
--descriptionis 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.--acceptancetakes one criterion per flag, each a statement that can be checked off as true or false.--plantakes one step per flag, numbered for you.--priorityruns 1 (most urgent) to 5 (least), and is left unset if omitted.--duetakesYYYY-MM-DDand nothing else. Anything that is not a real calendar date in that exact form,2026-8-9and2026-02-30included, is a usage error with nothing written. The same parser guardsset --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 append 1b78a24 --tags tui # add a tag, keeping the ones there
worklane chown alice 1b78a24 # hand the ticket to someone
worklane chown --clear 1b78a24 # hand it back to nobody
set replaces, append adds, --clear empties. set --tags overwrites the whole
field, so use append --tags to add a tag to a ticket that already carries some: it
keeps what is there, and a tag the ticket already has is reported as no change rather
than added twice, so you do not have to read the ticket first. Several in one call by
repeating the flag or by separating them with commas, --tags "bug, tui", since that is
how the field itself is written. Reach for set --tags when the whole list is being
replaced, and set --clear tags to empty it: append has neither. 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 five status directories and the campaigns
directory beside them, for a repo that has no board yet.
A board can be shared across machines. .worklane is gitignored and not itself a git
repo, so a clone elsewhere has no board. The shared layout keeps one boards repo cloned
once per machine, a committed .worklane.toml in the project naming its board, and
.worklane as a symlink into the boards directory — transparent to every command. Where
to run init decides the layout: a project whose machine carries a boards config, or
whose repo already shows a .worklane.toml, lands on the shared board, and everything
else gets the ordinary local .worklane. A pointer whose board is missing is an unsynced
machine and init refuses rather than creating a second board that would have to be
merged by hand; worklane init --create is the deliberate exception for a genuinely new
board. You only need the layout in mind when a .worklane.toml appears in a repo you
are working in: it says the board is another machine's, and a missing one means pull the
boards repo, not that the board never existed.
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
worklane relate 1b78a24 --clear blocked-by 4179958 # take that edge off again
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.
--clear is how an edge comes off, and it names the kind and the target, because a
ticket can hold several relations of one kind and emptying all of them is rarely what is
wanted. Repeat the flag for more. The kind is spelled either way, blocked-by as the flag
records it or blocked by as show prints it. set --clear does not reach relations:
relate is the only writer of the section, so it owns both directions.
The target is resolved against the edges the ticket already holds first, by id prefix,
and only then as an ordinary ticket search. That order is what lets you clear an edge
whose target has been deleted, which is the case most likely to need it: show draws
it as _missing_ with a ? mark and mv warns about it on every move, and no search of
the board can reach a ticket that is gone.
An edge the ticket does not hold reports no change. A target that names nothing at all is
an error rather than a no-op, so a mistyped id does not read as success. Recording and
clearing the same edge in one call is refused outright, the way set refuses a field it
is also replacing, and nothing is written. 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.
relates to reads the same from both ends, so recording it on the second ticket is
refused as no change: the edge is already there, from the far side. blocked by and
regression of are different: the far end reads as blocks and regressed by, so two
tickets each blocking the other is two facts and the block shows both. A symmetric edge
comes off with --clear at the end that stores it, since that is the only end holding a
line to remove.
--blocked-by is enforced by the column: a ticket cannot move to a status ahead of
the one its blocker is in, and standing level with it is allowed. So a blocker in
reviewing lets the dependent be committed and submitted for review and refuses only
done; a blocker still in backlog holds the dependent in backlog. With several
blockers the least advanced one sets the ceiling, and the refusal names the status you
tried to move to and every blocker still behind it. A blocker in done or discarded
holds up nothing at all.
That is what makes it worth recording an edge on work you are about to start rather than
work you have finished: waiting on a ticket in review costs nothing until the last move.
-f moves past it anyway, beside the backward and skipping moves it already allows. It
is enforced from the other end too: discarding a ticket that open tickets are blocked by
is refused, naming them. 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 or
discarded, 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 apart, and done from discarded, since each
pair shares a glyph, and your output is a pipe, so you do not get the colour. Read
◐ as under way and ● as nothing left to do, and if it matters which of the two,
worklane show on that target says so in its Status field. ○ is unambiguous without it.
A row pointing at a discarded target is struck through on a terminal, since a relation to abandoned work otherwise reads as a live dependency. That is a style rather than a character, so a pipe does not get it either: ask the target's Status field.
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 --state open # only the ones with work left: open, done, empty
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, append --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 entry carries an author, and yours comes from WORKLANE_ACTOR, which your harness
sets before you run anything. Assume it is set for you, and never spell yourself out on
a call — a plain worklane comment is already attributed to you, which is what keeps a
board several agents write to saying which of them said what. It is configured once,
where your session's environment lives: 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.
Reach for --actor only when the entry is somebody else's action: the person asked
you to move a ticket, or to put words on the board as their comment, so name them on
the flag — the move was theirs and the words are theirs, and an entry carrying your name
reads later as though you decided both. Otherwise leave it off, unless your instructions
say to use it. It is spelled the same on every command that writes an entry: comment,
mv, chown, set, append and assign. On the last two it reaches only the entry
--tags writes, since that is the one field either of them logs.
Acting for the person without knowing how they spell themselves? --actor-from-git
attributes the entry to the detected git user instead of WORKLANE_ACTOR, so their name
is never needed. It cannot be combined with --actor, and a machine with no git user
configured has nobody to name: the entry reads unknown rather than falling back to your
variable.
worklane mv 1b78a24 --status done --actor "Ansho Rei"
Under a missing or empty variable the author falls back to the git user of the machine —
the human whose checkout it is — and with neither, unknown. It is free text, checked
against nothing: whatever name you pass, make it one 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.
An entry made from the board is the person's, not yours. A command typed at the
board's : prompt is attributed to the git user of that machine whatever WORKLANE_ACTOR
is set to, because nothing but the person sitting at the board can type one. So an entry
can appear under a name no agent is configured with, and reading it as somebody else's
agent is reading it wrong: that is the person whose board it is, acting for themselves.
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:
- a UUID prefix, from four characters up
- a substring of the title
- 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,--planand thecommentbody. A criterion reading--print is supportedis 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 withworklane show. --due,--priority,--tags,--owner,--actorand--statusdo 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--clearfor it named. commenthas no--owner. Owner is the ticket's assignee, whichchownwrites; the author of a comment is--actororWORKLANE_ACTOR. The old spelling is a usage error, not an alias.- Piping is safe:
worklane ls | head -3exits on the closed pipe instead of panicking.